Setup guide

Lets the skill issue GET, POST, PUT and DELETE against api.hetzner.cloud/v1 — creating SSH keys, networks, subnets, firewalls, placement groups, servers, volumes, load balancers, floating IPs, snapshots, and enabling backups.

↳ Use a Read token for the sizing, inventory and cost-modelling paths (server-type list, datacenter list, server describe). A Read token can only issue GET, so it physically cannot provision or delete.

Sufficient for the whole cost-model and audit half of the skill: hcloud server-type list, hcloud datacenter list, hcloud server list --selector, hcloud server describe, load-balancer health inspection.

↳ This is already the least-privilege option; mint a second Read-only token for CI cost reporting so the provisioning token never leaves the deploy pipeline.

Authenticates every call to https://robot-ws.your-server.de — listing dedicated servers, activating the rescue system, triggering hardware resets, creating vSwitches and assigning servers to them, setting rDNS on dedicated IPs, and querying traffic.

↳ None exists. The Robot webservice is account-wide and unscoped: one credential can reset, reinstall, re-route and order hardware for every server on the account, including server_ordering. If you need blast-radius control, put production metal in a separate Hetzner account rather than trying to scope the credential.

Authorises the offsite backup path — aws s3 sync ... --endpoint-url https://fsn1.your-objectstorage.com — used because Hetzner automatic backups are 7 slots inside the same failure domain and are not disaster recovery.

↳ By default each key pair can reach every bucket in the same project. Put backup buckets in a dedicated project so a leaked backup key cannot read or delete production objects.

Opens the extended SSH service on port 23 so BorgBackup and rsync can write the offsite copy; without it the Storage Box only speaks SMB/WebDAV/FTP.

↳ Create a Storage Box sub-account restricted to a single sub-directory and give that to the backup host, instead of handing out the main uXXXXXX account which owns the whole box.

Cause: HCLOUD_TOKEN is empty, truncated, revoked, or belongs to a deleted project. Tokens are project-scoped, so a token minted in project A returns this against project B's resources.

Fix: Re-mint the token in Hetzner Console > project > Security > API tokens > Generate API token and re-run hcloud context create. Verify the exported value is the full 64 characters with no trailing newline (printf '%s' "$HCLOUD_TOKEN" | wc -c).

Cause: The Cloud token was created with the Read permission, so POST/PUT/DELETE are rejected — typically hit on hcloud server create, firewall add-rule, or terraform apply.

Fix: Create a second token with Read & Write. Token permission cannot be changed after creation; you must generate a new one and delete the old.

Cause: The Cloud API allows roughly 3600 requests per hour per project and the code is polling per-server in a loop instead of filtering server-side.

Fix: Replace per-server loops with a single labelled query (hcloud server list --selector role=app, or GET /v1/servers?label_selector=role%3Dapp) and back off on the RateLimit-Reset response header.

Cause: The requested server type is sold out in that location — very common for CAX (Ampere) and CCX types in fsn1/nbg1 — or the spread placement group has no free physical host left.

Fix: Re-check live availability with hcloud server-type list and hcloud datacenter list, then try a sibling location in the same network zone (fsn1/nbg1/hel1 are all eu-central) or a different type family. Do not hardcode SKU names.

Cause: The project hit its default quota for servers, volumes, floating IPs or primary IPs. New projects ship with modest limits.

Fix: File a limit-increase request from Hetzner Console; it is a support ticket with real lead time. Meanwhile, free unused primary IPs (--without-ipv4 avoids allocating them at all) and delete orphaned snapshots.

Cause: The Robot webservice user has not been activated, or the Robot web-login password is being sent instead of the separate webservice password.

Fix: Robot > user menu (upper right) > Settings > Web service and app settings > set the web service password. After three bad attempts wait out the 10-minute source-IP block before retrying — retry loops extend it.

Cause: The Robot API is rate-limited far more tightly than the Cloud API: about 200 requests/hour by default, 50/hour for reset, and 10/hour for failover and wake-on-LAN.

Fix: Cache Robot responses (the server inventory changes rarely), never poll rescue or reset status in a tight loop, and drive automation from a single scheduled sync rather than per-action lookups.

Cause: Rescue was requested for a server that does not support the chosen boot option, or rescue is already active, or the server-number/IP in the path is wrong.

Fix: GET /boot/{server-number} first to read the available options, DELETE /boot/{server-number}/rescue to clear a stale activation, and confirm the identifier with GET /server.

Cause: A manual reset request is already queued for that dedicated server, so POST /reset/{server-number} is rejected.

Fix: Wait for the pending reset to complete before issuing another; check GET /reset/{server-number} for the currently available reset types instead of retrying blindly.

Cause: The SSH key was uploaded to the Cloud project but not to Robot key management (or vice versa) — the two systems do not share key stores — or the server was created without --ssh-key and cloud-init authorised nothing.

Fix: Upload the same public key to both Hetzner Console > Security > SSH keys and Robot > Key management. For an already-broken Cloud server, boot the Cloud rescue system and re-add the key; for metal, activate the Robot rescue system with the correct KEY_FINGERPRINT.

Cause: hcloud CLI is older than 1.45; the flags the skill relies on (--without-ipv4, --placement-group, --firewall) do not exist in older builds.

Fix: Upgrade the CLI from the hetznercloud/cli releases and confirm with hcloud version before running any provisioning script.