Appearance
Connect Hetzner
Connecting a Hetzner Cloud project gives Kadmo an API token it uses to manage agent machines in that project. You create one Read & Write token in the Hetzner Cloud Console and paste it into the app. This guide covers the token, where it goes in the app, the locations and sizes Kadmo offers, what Kadmo creates in your project, and the fix for every error the app shows.
In this release
You can connect a Hetzner project, but the app does not launch agents on Hetzner yet. The app reaches agents over Kadmo's private network, and a Hetzner server has no private path to it. A launch on a Hetzner connection is refused with:
"Hetzner agents have no private network this app can reach yet — launch on an AWS connection with an agent subnet"
To run agents now, use AWS or request a hosted agent.
Before you start
- A Hetzner Cloud account, and a project you can create API tokens in.
- The admin role on your Kadmo account: cloud connections are admin-only.
- About five minutes.
Step 1: Create or pick a project
In the Hetzner Cloud Console, create a project for your agents, for example kadmo-agents, or open an existing one. A project of its own keeps agent servers, firewalls and SSH keys apart from everything else, and its bill is the agent spend.
Step 2: Create an API token
- In the project, open Security → API tokens.
- Click Generate API token.
- Give it a description, for example
kadmo-agents, and choose Read & Write. A read-only token cannot create servers. - Copy the token. Hetzner shows it only once.
Hetzner tokens have no finer scopes: a Read & Write token covers every operation in its project, which is one more reason to give agents a project of their own.
Step 3: Connect in the app
- In the app, open Integrations and, in the Cloud group, open the Hetzner card. (On an empty Agent Fleet page, Connect next to Hetzner goes to the same place.)
- Click Connect Hetzner account. The Connect Hetzner account panel opens.
- Fill in:
| Field | What to enter |
|---|---|
| Display name | A name for this connection, for example kadmo-agents |
| API token | The Read & Write token from Step 2 |
| Default location | Optional: the location new agents start in |
- Click Connect & validate. The app checks the token by listing Hetzner's locations, stores it encrypted, and creates your account's firewall (below). "Hetzner account connected." means you are done.
The Hetzner card
Once connected, the card shows the Connection, Region, Status and when it was Validated. Its buttons:
| Button | What it does |
|---|---|
| Validate | Checks the stored token again: "Credentials valid ✓" |
| Rotate credentials | Replaces the token (Rotate & validate) and keeps the connection's name |
| Disconnect | Removes the connection and the account firewall. Refused while agents still use it |
Locations and sizes
The create-agent wizard offers these locations:
| Location | City |
|---|---|
fsn1 | Falkenstein |
nbg1 | Nuremberg |
hel1 | Helsinki |
ash | Ashburn, VA |
hil | Hillsboro, OR |
sin | Singapore |
And these sizes (Kadmo's catalogue estimate per month; Hetzner bills its own list price):
| Size | Server type | vCPU | Memory | About |
|---|---|---|---|---|
| Small | CX23 | 2 | 4 GB | $5 |
| Medium (default) | CX33 | 4 | 8 GB | $9 |
| Large | CX43 | 8 | 16 GB | $19 |
| XL | CCX23 (dedicated vCPU) | 4 | 16 GB | $53 |
- The wizard asks Hetzner which server types each location sells right now. The CX line is not sold in every location (for example in
ash,hilandsin); a size Hetzner does not offer, or has sold out, is greyed out. Load N more sizes the provider stocks right now shows other server types from Hetzner's live catalogue. - Hetzner has no spot market, so there is no spot option.
- No Hetzner Cloud type offers KVM, so the Android Emulator cannot run on Hetzner.
What Kadmo creates in your project
| Resource | Name and labels | When |
|---|---|---|
| Firewall, one per account, shared by every agent | kadmo-acct-<account-id> | When you connect (or at the first launch) |
| SSH key, one per agent | kadmo-<agent-name>; labels kadmo/managed, kadmo/agent | At launch. The private key is kept, encrypted, for Settings → Agents → SSH Access |
| Server | The agent's name; image ubuntu-24.04; labels kadmo/managed, kadmo/agent, kadmo/tier; the account firewall attached | At launch |
The firewall admits:
| Port | From | Why |
|---|---|---|
| 9876 (TCP) and ICMP | Kadmo's app network only | The app talks to the agent runtime |
| 22 (SSH) and 3389 (RDP) | The addresses on your firewall allowlist and, where Kadmo's deployment names them, Kadmo's operations ranges | So people can reach the machine directly |
The address you connect from is added to the allowlist. Edit the list under Settings → Cloud → Firewall allowlist (Add, Add my current IP, Save allowlist). You never type a Kadmo address into Hetzner: the app writes the rules.
Destroy on an agent's page deletes its server and its SSH key. Disconnecting deletes the account firewall.
Troubleshooting
Each row is a message the app shows and its fix.
| Message | Cause | Fix |
|---|---|---|
| "This token is read-only. Generate a Read & Write token in Hetzner Console." | The token was created as Read | Create a Read & Write token (Step 2) and connect again, or use Rotate credentials |
| "Credential validation failed" | The token is wrong, revoked, or from a deleted project | Copy the token again, or create a new one |
| "API token is required" / "Display name is required" | A field is empty | Fill in both |
| "Validation failed: …" (Hetzner card) | The stored token no longer works | Rotate credentials with a working token |
| "Hetzner agents have no private network this app can reach yet — launch on an AWS connection with an agent subnet" | Launching on Hetzner is not available in this release | Use AWS or a hosted agent |
| "… is not offered in … — available in: …. Pick another machine size or location." | The size is not sold in that location | Pick a listed location, another size, or Load N more sizes |
| "… is temporarily sold out in … — pick another machine size or location, or retry later." | Hetzner has no capacity for that type there right now | Pick another size or location, or retry later |
| "… is deprecated in … — unavailable after …" | A warning: Hetzner is retiring the type there | Prefer another size for long-lived agents |
| "… is not in Hetzner's current catalogue — the pricing table may be out of date." | Hetzner no longer lists the type | Pick another size, or Load N more sizes |
| "Could not check availability at Hetzner: … Launch may still fail if the size is sold out here." | The check could not reach Hetzner | A warning only; Hetzner decides at launch |
| "Cannot delete connection: agents are still referencing it" | Agents still use the connection | Destroy or move the agents first, then disconnect |
Security notes
- The token is stored encrypted (AES-256-GCM) and never returned by the app.
- Give agents a project of their own: the token can act on everything in its project.
- To rotate, create a new token in Hetzner, use Rotate credentials in the app, then delete the old token.
Next step
Until Hetzner launches are available, create agents on AWS with the create-agent wizard, or request a hosted agent.