Das Panel mit API-Schlüsseln und der CLI automatisieren

Alles, was du im Panel anklicken kannst, geht auch aus einem Skript: Apps auflisten, ein neues Image ausrollen, Logs lesen, DNS-Einträge ändern. Der Schlüssel dazu ist ein API-Schlüssel, und am einfachsten nutzt du ihn mit der Kommandozeile headpat. Diese Anleitung behandelt beides.

Was du brauchst

Ein Headpat-Space-Konto mit bestätigter E-Mail-Adresse.
Für die CLI: einen Rechner mit Linux, macOS oder Windows. Es ist keine Laufzeitumgebung zu installieren; die CLI ist eine einzelne Datei.

1. API-Schlüssel anlegen

Melde dich im Panel an, öffne API-Schlüssel in der Seitenleiste.
Klicke auf API-Schlüssel erstellen.
Gib einen Schlüsselnamen, der sagt, wo der Schlüssel eingesetzt wird, zum Beispiel GitHub Actions - shop.
Hake unter Scopes nur an, was das Skript braucht. Scopes sind gruppiert (Apps, VMs, Gameserver, Domains, DNS und so weiter), jeweils mit Read und Write. Read lässt einen Schlüssel nachsehen; Write lässt ihn anlegen, ändern und löschen. Einige Scopes sind als Gefährlich markiert, weil sie in deine Dienste hineingreifen, etwa Befehle in einer App ausführen oder ihre Dateien bearbeiten; sie müssen ausdrücklich eingeschaltet werden.
Auf bestimmte Ressourcen beschränken ist optional. Wählst du etwa eine einzige App, kann der Schlüssel keine andere App sehen oder anfassen, auch wenn seine Scopes es erlauben würden. Nutze das für Deploy-Schlüssel.
Wähle einen Ablauf. Schlüssel, die nie ablaufen, solltest du von Hand gelegentlich erneuern.
Klicke auf Schlüssel erstellen. Der Schlüssel wird genau einmal angezeigt. Kopiere ihn in deinen Passwortmanager oder den Secret-Speicher deiner CI, bevor du den Dialog schließt; danach ist nur noch sein Präfix sichtbar.

Ein Schlüssel, der bezahlte Dienste anlegen darf, braucht eine Standard-Zahlungsmethode im Konto; sonst scheitern diese Aufrufe mit einer entsprechenden Meldung.

2. CLI installieren

Unter Linux und macOS:

curl -fsSL https://headpat.space/install.sh | sh

Unter Windows, in PowerShell:

irm https://headpat.space/install.ps1 | iex

Das Skript wählt den passenden Build für dein System, prüft ihn gegen die veröffentlichten Prüfsummen und installiert headpat nach ~/.local/bin (unter Windows nach %LOCALAPPDATA%\Programs\headpat, das es zu deinem PATH hinzufügt). Liegt ~/.local/bin noch nicht in deinem PATH, zeigt das Skript die Zeile, die du ergänzen musst. Unter Alpine Linux führe vorher apk add libstdc++ libgcc aus.

Mit Node.js 18 oder neuer kannst du die Installation überspringen: npx @headpat/cli apps list startet dieselbe CLI, und npm i -g @headpat/cli installiert sie als headpat.

Zum Installieren von Hand lädst du die Datei für dein System aus dem neuesten Release. macOS kann eine im Browser geladene Datei beim ersten Start ablehnen; erlaube sie unter Systemeinstellungen, Datenschutz & Sicherheit.

Dann anmelden:

headpat login

Die CLI öffnet das Panel in deinem Browser; über SSH zeigt sie stattdessen den Link. Prüfe, ob die Seite denselben Code zeigt wie dein Terminal, hake die Berechtigungen an, die die CLI nutzen darf, und klicke auf Bestätigen. Die CLI erhält einen neuen API-Schlüssel mit dem Namen deines Rechners und speichert ihn in einer Konfigurationsdatei, die nur dein Benutzer lesen kann (~/.config/headpat/config.json, unter Windows %APPDATA%\headpat\config.json). Dieser Schlüssel läuft nicht ab; du kannst ihn jederzeit unter API-Schlüssel einschränken oder widerrufen. Um stattdessen einen Schlüssel aus Schritt 1 zu hinterlegen, führe headpat login --paste-key aus. In Skripten setzt du die Umgebungsvariable HEADPAT_API_KEY; sie hat Vorrang vor der Datei.

Mit headpat update bringst du die CLI später auf die neueste Version.

3. Befehle für den Alltag

headpat apps list
headpat apps get <app-id>
headpat apps logs <app-id> --tail 200
headpat apps restart <app-id>
headpat apps db query <app-id> "select count(*) from orders"
headpat dns records <zone-id>
headpat dns set-record <zone-id> www.example.com A --content 203.0.113.4
headpat vms list
headpat game-servers power <server-id> restart

headpat --help zeigt alle Gruppen, headpat apps --help alle Befehle einer Gruppe und headpat apps create --help die Optionen eines Befehls. Hänge an jeden Befehl --json an, um die rohe API-Antwort zu bekommen, was du in Skripten willst:

headpat apps list --json | jq -r '.[] | select(.status != "running") | .displayName'

Wird ein Befehl abgelehnt, nennt die Fehlermeldung den Scope, der dem Schlüssel fehlt, sodass du genau weißt, was zu ergänzen ist.

4. Eine Container App aus der CI ausrollen

Der häufigste Fall: in der CI ein Image bauen und dann dem Panel sagen, dass es dieses Image betreiben soll. Die ID der App steht in ihrer URL im Panel (die lange Kennung nach /apps/).

# .github/workflows/deploy.yml
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
      - name: Install headpat
        run: |
          curl -sL -o headpat https://github.com/HeadpatCloud/headpat-cli/releases/latest/download/headpat-linux-x64
          chmod +x headpat
      - name: Roll out
        env:
          HEADPAT_API_KEY: ${{ secrets.HEADPAT_API_KEY }}
        run: ./headpat apps config ${{ vars.HEADPAT_APP_ID }} --image ghcr.io/${{ github.repository }}:${{ github.sha }}

Für diesen Schlüssel reicht Apps: Write, beschränkt auf diese eine App. Das Panel zieht das neue Image und startet die App neu; headpat apps status <app-id> zeigt, wann sie wieder läuft. Ist das Image privat, hinterlege die Registry-Zugangsdaten einmal in der Karte Konfiguration der App im Panel; die CLI ändert nur den Tag.

5. Alles Weitere in der API

Die CLI hat Befehle für die üblichen Aufgaben. Die API hat einige hundert Operationen, dokumentiert unter api.headpat.space/api/docs. Jede davon lässt sich über ihren Namen aufrufen:

headpat api apps.sshKeys.list --input '{"appId":"<app-id>"}'
headpat api billing.invoices

Ohne CLI sind dieselben Aufrufe gewöhnliche HTTPS-Anfragen mit dem Schlüssel als Bearer-Token:

curl -H "Authorization: Bearer $HEADPAT_API_KEY" https://api.headpat.space/api/v1/apps/list

Die Limits stehen im Header RateLimit-Remaining; Skripte in Schleifen sollten Retry-After bei einer 429 beachten.

Schlüssel sicher halten

Ein Schlüssel pro Zweck. Ein Deploy-Schlüssel, der auf eine App beschränkt ist, kann anderswo keinen Schaden anrichten, wenn er durchsickert.
Die Spalte Zuletzt verwendet auf der Seite API-Schlüssel zeigt, ob ein Schlüssel noch in Gebrauch ist. Deaktivieren stoppt einen Schlüssel sofort, ohne ihn zu löschen; Aktivieren schaltet ihn wieder ein.
Scope-Änderungen gelten ab der nächsten Anfrage; der Schlüssel selbst bleibt gleich, du kannst ihn also einschränken, ohne das Skript neu auszurollen, das ihn nutzt.
Lege nie einen Schlüssel in ein Repository. Ist einer durchgesickert, lösche ihn im Panel und erstelle einen neuen.