/hetzner-cloud

name: hetzner-cloud
description: "Read and operate Hetzner Cloud servers, server types, locations, networks, volumes, snapshots, and cost estimates through gateway-proxied API requests."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: hetzner-api-token
    kind: bearer
    required: true
    secret_ref:
      source: store
      id: HETZNER_API_TOKEN
    scope: "api.hetzner.cloud/v1"
    how_to_obtain: "Create a Hetzner Console API token for the target project with read-only scope for inventory work or read-write scope only when provisioning, snapshotting, restoring, or deleting resources. Set `HETZNER_API_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HETZNER_API_TOKEN \"<hetzner-console-api-token>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HETZNER_API_TOKEN \"<hetzner-console-api-token>\"`."
metadata:
  hybridclaw:
    category: infrastructure
    short_description: "Hetzner Cloud VPS inventory, provisioning, resizing, snapshots, and guarded deletes."
    tags:
      - hetzner
      - cloud
      - vps
      - snapshots
      - infrastructure
    stakes_tiers:
      green:
        - list-servers
        - get-server
        - list-server-types
        - list-locations
        - list-images
        - list-prices
        - list-volumes
        - get-volume
        - list-networks
        - get-network
      amber:
        - create-server
        - create-volume
        - create-snapshot
        - attach-volume
        - detach-volume
        - attach-network
        - detach-network
        - change-server-type
        - upgrade-server
        - downgrade-server
      red:
        - restore-snapshot
        - delete-server
        - delete-vps
        - delete-snapshot
        - destroy-snapshot
        - delete-volume
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: hetzner-cloud

Hetzner Cloud

Use this skill for Hetzner Cloud VPS inventory, provisioning, network and volume inspection, cost estimates, and snapshot lifecycle work.

Default Workflow

1. Start read-only: list servers, locations, server types, images, prices, volumes, and networks. 2. Use `plan` for natural-language requests before building any write request. 3. Treat `hetzner_cloud.cjs` as the API wrapper. Do not handcraft Hetzner Cloud API URLs, JSON bodies, tiers, or secret refs from memory. 4. For prompt/user testing, stop after `plan` or after helper `http-request` payload generation. Do not call helper `run` or the built-in `http_request` tool. 5. For real user requests that need live Hetzner API data, use helper `run`. The helper constructs the request, sends it through the HybridClaw gateway, and the gateway injects `bearerSecretName: "HETZNER_API_TOKEN"` server-side. Do not rewrite that secret reference into `secretHeaders`, preflight it, inspect it, or ask the model for the token. 6. Use `http-request` only when you need to inspect the generated gateway payload or when the active runtime cannot give the helper gateway access. 7. If a live helper `run` or `http_request` call returns 401 or 403, stop after that first failure. Do not retry, do not fan out to more endpoints, and ask the operator to set or verify `HETZNER_API_TOKEN`. 8. Require an explicit operator grant before any changing action, including delete, upgrade, downgrade, buy/create, restore, attach, detach, snapshot, network, or volume mutation. Pass `--operator-grant` only after that grant. 9. Use `--project acme` for project-scoped inventory and provisioning. The helper converts it to `project=acme` label selectors or labels where the Hetzner API supports them. 10. Never paste, print, or inspect `HETZNER_API_TOKEN`; the gateway injects it server-side with `bearerSecretName: "HETZNER_API_TOKEN"`. 11. Do not repeat the same read call unless the previous result was ambiguous or stale. For a named resize, one `list-servers --project <project> --name <name>` call is enough to resolve the server id.

See [references/operator-setup.md](references/operator-setup.md) for operator setup, token scope, autonomy defaults, and cost-reporting expectations.

Command Contract

Run the helper:

node skills/hetzner-cloud/hetzner_cloud.cjs --help

Plan a request without contacting Hetzner:

node skills/hetzner-cloud/hetzner_cloud.cjs --format json plan "Create a demo VPS in Falkenstein until Monday"

Run live read requests:

node skills/hetzner-cloud/hetzner_cloud.cjs --format json run list-servers --project acme
node skills/hetzner-cloud/hetzner_cloud.cjs --format json run list-server-types
node skills/hetzner-cloud/hetzner_cloud.cjs --format json run list-locations
node skills/hetzner-cloud/hetzner_cloud.cjs --format json run list-prices --project acme
node skills/hetzner-cloud/hetzner_cloud.cjs --format json run list-volumes --project acme
node skills/hetzner-cloud/hetzner_cloud.cjs --format json run list-networks --project acme

Run guarded live write requests:

node skills/hetzner-cloud/hetzner_cloud.cjs --format json run create-server \
  --name acme-demo --server-type cax11 --image ubuntu-24.04 --location fsn1 \
  --project acme --label ttl=2026-05-18 --operator-grant

node skills/hetzner-cloud/hetzner_cloud.cjs --format json run create-snapshot \
  --project acme --server-id 123456 --description "pre-deploy" --operator-grant

node skills/hetzner-cloud/hetzner_cloud.cjs --format json run restore-snapshot \
  --server-id 123456 --snapshot-id 987654 --operator-grant

node skills/hetzner-cloud/hetzner_cloud.cjs --format json run attach-network \
  --server-id 123456 --network-id 555 --ip 10.0.0.12 --operator-grant

node skills/hetzner-cloud/hetzner_cloud.cjs --format json run attach-volume \
  --server-id 123456 --volume-id 777 --automount --opera