Automate the panel with API keys and the CLI

Everything you can click in the panel can also be done from a script: list your apps, roll out a new image, read logs, change DNS records. The key to that is an API key, and the easiest way to use one is the headpat command line. This guide covers both.

What you need

A Headpat Space account with a verified email address.
For the CLI: a computer running Linux, macOS or Windows. No runtime to install; the CLI is a single file.

1. Create an API key

Sign in to the panel, open API Keys in the sidebar.
Click Create API Key.
Give it a Key Name that says where it will be used, for example GitHub Actions - shop.
Under Scopes, tick only what the script needs. Scopes come in groups (Apps, VMs, Game servers, Domains, DNS, and so on), each with Read and Write. Read lets a key look at things; Write lets it create, change and delete them. A few scopes are marked Dangerous because they reach inside your services, such as running commands in an app or editing its files; they need an explicit opt-in.
Restrict to specific resources is optional. When you pick, say, one app, the key cannot see or touch any other app even if its scopes would allow it. Use it for deploy keys.
Choose an Expiry. Keys that never expire should be rotated by hand now and then.
Click Create Key. The key is shown exactly once. Copy it into your password manager or CI secret store before closing the dialog; afterwards only its prefix is visible.

A key that may create paid resources needs a default payment method on your account, otherwise those calls fail with a message saying so.

2. Install the CLI

On Linux and macOS:

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

On Windows, in PowerShell:

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

The script picks the build for your system, checks it against the published checksums and installs headpat in ~/.local/bin (on Windows in %LOCALAPPDATA%\Programs\headpat, which it adds to your PATH). If ~/.local/bin is not on your PATH yet, the script prints the line to add. On Alpine Linux, run apk add libstdc++ libgcc first.

With Node.js 18 or newer you can skip the install: npx @headpat/cli apps list runs the same CLI, and npm i -g @headpat/cli installs it as headpat.

To install by hand, download the file for your platform from the latest release. macOS may refuse a file downloaded in the browser on first start; allow it under System Settings, Privacy & Security.

Then log in:

headpat login

The CLI opens the panel in your browser; over SSH it prints the link instead. Check that the page shows the same code as your terminal, tick the permissions the CLI may use and click Approve. The CLI receives a new API key named after your computer and saves it to a config file only your user can read (~/.config/headpat/config.json, or %APPDATA%\headpat\config.json on Windows). That key does not expire; narrow or revoke it any time under API Keys. To store a key from step 1 instead, run headpat login --paste-key. In scripts, set the environment variable HEADPAT_API_KEY; it takes precedence over the file.

headpat update brings the CLI to the latest version later on.

3. Everyday commands

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 lists every group, headpat apps --help every command in a group, and headpat apps create --help the flags of one command. Add --json to any command to get the raw API response, which is what you want in scripts:

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

When a command is refused, the error names the scope the key is missing, so you know exactly what to add to it.

4. Deploy a Container App from CI

The most common use: build an image in CI, then tell the panel to run it. The app's id is in its URL in the panel (the long identifier after /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 }}

For this key, Apps: Write restricted to that one app is enough. The panel pulls the new image and restarts the app; headpat apps status <app-id> shows when it is running again. If the image is private, set the registry credentials once in the app's Configuration card in the panel; the CLI only changes the tag.

5. Everything else in the API

The CLI has commands for the common tasks. The API has a few hundred operations, documented at api.headpat.space/api/docs. Any of them can be called by name:

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

Without the CLI, the same calls are plain HTTPS with the key as a bearer token:

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

Rate limits are returned in the RateLimit-Remaining header; scripts that loop should respect Retry-After on a 429.

Keeping keys safe

One key per purpose. A deploy key restricted to one app cannot do harm elsewhere when it leaks.
The Last used column on the API Keys page shows whether a key is still in use. Disable stops a key immediately without deleting it; Enable brings it back.
Scope changes apply on the next request; the key itself stays the same, so you can tighten a key without redeploying the script that uses it.
Never commit a key to a repository. If one leaks, delete it in the panel and create a new one.