Hetzner Connection Setup
This guide explains how to connect your Hetzner account to SideButton so you can provision and manage agent VMs directly from the portal.
Overview
SideButton provisions Hetzner servers on your behalf using a project-scoped API token with Read & Write permissions. Once connected, you can deploy agents with one click and SideButton handles the full VM lifecycle (create, reboot, stop, start, delete).
Prerequisites
- A Hetzner Cloud account
- An existing Hetzner project (or permission to create one)
Step 1: Create or select a Hetzner project
- Go to https://console.hetzner.com/ → Projects
- Use an existing project or click New Project to create one
Note: A Hetzner API token is scoped to a single project. If you want SideButton to manage agents in multiple Hetzner projects, create a separate connection for each project. (Multiple connections per provider are planned as a future enhancement — currently the portal supports one active Hetzner connection.)
Step 2: Generate an API token
Inside your project, go to Security → API Tokens → Generate API Token
Give it a descriptive name (e.g.,
sidebutton-agent-manager)Set permissions to Read & Write
⚠️ Read-only tokens are rejected by the portal with a
token_readonlyerror. Make sure you select Read & Write.Click Generate API Token
Copy the token immediately — Hetzner displays it only once and it cannot be retrieved later
Step 3: Connect in SideButton
- Open the SideButton portal → Integrations → Cloud
- On the Hetzner card click Connect to open the connection form
- Paste the API token from Step 2
- Optionally pick a Default Location (e.g.,
nbg1for Nuremberg,fsn1for Falkenstein,hel1for Helsinki,ashfor Ashburn US) - Click Connect & Validate — SideButton validates the token by calling
GET /v1/locationsagainst the Hetzner API and stores it encrypted
Once connected, the Hetzner card shows a green Connected badge.
Creating an agent on Hetzner
After connecting, any new agent you create can use your Hetzner connection:
- Go to Agents → Create Agent — the wizard opens with a chip in its header naming the cloud connection it will use; pick your Hetzner connection on the Machine step if it is not already selected
- Pick an agent profile and agent app on the Software step
- Choose a Location and Machine size (see table below) — a size Hetzner is out of in that location is greyed out and blocks Launch until you pick another, and Load 8 more sizes… reveals more of what Hetzner stocks there right now
- Click Launch — SideButton provisions the server, SSH key, and firewall automatically
Available regions
| Location code | Data center |
|---|---|
nbg1 | Nuremberg, Germany |
fsn1 | Falkenstein, Germany |
hel1 | Helsinki, Finland |
ash | Ashburn, VA, USA |
hil | Hillsboro, OR, USA |
sin | Singapore |
Available sizes and pricing
| Tier | Server type | vCPU | RAM | Monthly price |
|---|---|---|---|---|
| S | CX23 | 2 | 4 GB | ~$5 |
| M | CX33 | 4 | 8 GB | ~$9 |
| L | CX43 | 8 | 16 GB | ~$19 |
| LX | CCX23 (dedicated vCPU) | 4 | 8 GB | ~$53 |
Prices shown in USD equivalent. Hetzner bills in EUR; exact amounts vary with exchange rates. See Hetzner pricing for current rates.
Hetzner does not offer a spot/preemptible market — all instances are on-demand.
What SideButton creates in your Hetzner project
Provisioning through SideButton creates the following resources in your Hetzner project:
Shared account firewall (sidebutton-acct-<account id>) — created once per account (at connect, or lazily at the first provision) and attached to every agent server:
| Rule | Protocol | Port | Source |
|---|---|---|---|
| SSH | TCP | 22 | Operator allowlist |
| RDP | TCP | 3389 | Operator allowlist |
| SideButton control plane | TCP | 9876 | 46.225.225.112/32 |
| ICMP | ICMP | — | Any |
The SSH/RDP operator allowlist starts with the IP you connected from and is editable under Settings → Cloud Operations → Firewall allowlist. Agents created before the shared firewall existed carry a legacy per-agent firewall (sidebutton-agent-<name>), which is removed when that agent is deleted.
Server (named after the agent):
- OS: Ubuntu 24.04
- Labels:
sidebutton/managed=true,sidebutton/agent=<name>,sidebutton/tier=<S|M|L|LX>
SSH key (sb-<agent name>) — a per-agent keypair generated by SideButton. The public half is registered in the project and injected into root@; the private half is stored encrypted and surfaced in the portal's SSH key inventory (Settings → Cloud Operations).
You can inspect all created resources directly in the Hetzner Console under your project.
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
token_readonly | API token has Read-only permissions | Regenerate with Read & Write in Hetzner → Security → API Tokens |
token_invalid | Token was deleted or is malformed | Generate a new token and reconnect |
HTTP 429 (rate limit) | Too many API requests | Hetzner allows 3600 req/hr per project (replenishes 1/sec). Check for runaway list/poll loops |
| Server creation fails | Project resource quota exceeded | Request a quota increase in the Hetzner Cloud Console |
Security notes
- SideButton stores your API token encrypted with AES-256-GCM
- Tokens are never logged or exposed in API responses
- You can delete the connection at any time — SideButton will refuse deletion if agents are still attached
- Rotate your API token in Hetzner Console → Security → API Tokens and reconnect via Integrations → Cloud → Hetzner → Rotate credentials
Next step
Once your agent shows Online, connect it to your Claude subscription so Claude Code can authenticate and start working on jobs. Then send it work — see Orchestrating Agents.