Claiming

Claiming proves that a registered cluster is yours and attaches it to your kubehz account.

Registration only announces a cluster — it is created as pending, owned by nobody. Anyone could announce any domain, so ownership needs proof. There are two ways to provide it: the claim code printed at registration (simplest), or verifying that the SSH key that provisioned the cluster exists in your Hetzner Cloud account.

Option 1 — claim code (simplest)

Registration prints a one-time claim code. Have one? Then claiming is a single paste:

1. Open the dashboard at app.kubehz.cloud and sign in
2. Go to the Claim page
3. Paste the claim code — done. The cluster attaches to your tenant and its detail page opens.

A few properties worth knowing:

• Provider-agnostic — the code works without any Hetzner token, for any cluster.
• Consumed on use — a code claims exactly one cluster, once.
• No oracle — a wrong, expired, or already-used code all return the same "not found" answer; the claim page does not reveal which it was. If your code no longer works, fall back to the fingerprint verification below or re-register to get a new code.

Option 2 — SSH fingerprint + Hetzner token

No claim code at hand? Prove ownership through the SSH key that provisioned the cluster: it must exist in your Hetzner Cloud account.

What you need

1. The MD5 fingerprint printed by lo provision / lo kubehz register. You can recompute it at any time from the public key configured in your cluster.lok8s.yaml (spec.hcloud.sshPublicKeyFile):

   ssh-keygen -E md5 -lf ~/.ssh/id_ed25519.pub

2. A Hetzner Cloud API token for the project that holds that SSH key. A read-only token is sufficient. Create one in the Hetzner Cloud Console under Security → API tokens.

Claim the cluster

1. Open the dashboard at app.kubehz.cloud and sign in
2. Go to the Claim page
3. Paste the fingerprint — MD5:aa:bb:cc:… or the bare aa:bb:cc:… form, both are accepted
4. Paste your Hetzner Cloud API token
5. Click Claim Cluster

kubehz uses the token once, server-side, to list the SSH keys in your Hetzner project and check that one of them matches the fingerprint. On success the cluster attaches to your tenant and its detail page opens.

How your Hetzner token is handled

• Used once — a single lookup of your SSH keys at claim time, nothing else
• Never stored — discarded immediately after verification; it is not written to the database and not logged
• Least privilege — a read-only token is enough; kubehz never creates, modifies, or deletes anything in your Hetzner account
• Best practice: create a dedicated token just for the claim and delete it in the Hetzner Console afterwards

Security notes

• The fingerprint is public information: it identifies your public key but cannot impersonate you. That is exactly why the fingerprint path additionally requires the Hetzner token check.
• The platform never connects into your cluster. Health data flows outbound-only, via the heartbeat CronJob.
• If verification fails, the dashboard reports it ("Claim verification failed") and nothing is attached.

After claiming

• The cluster leaves pending and appears in your cluster list immediately
• Health details (nodes, component health, certificate expiry) fill in as heartbeats arrive, refreshed every 5 minutes
• Connected means a heartbeat was received in the last 15 minutes; the dashboard also derives a 30-day uptime from heartbeat history

Troubleshooting

Symptom	Fix
Claim code "not found"	Codes are one-time and expire with the pending registration — re-register to get a fresh code, or use the fingerprint + token path
Fingerprint not accepted	Recompute with ssh-keygen -E md5 — kubehz matches the MD5 form, because Hetzner exposes MD5 fingerprints
Verification fails despite correct fingerprint	Make sure the token belongs to the Hetzner project that actually holds the SSH key
Key missing from Hetzner	The public key from cluster.lok8s.yaml must exist in your Hetzner Cloud project (it does if lok8s provisioned the cluster with it)
Cluster not registered yet	Run lo kubehz register first — see Registration

Next steps

• Dashboard — what you can see and do after claiming
• Registration — the CLI half of the handshake
• Pricing — what the free tier covers

---

Doc status

Aspect	Detail
State	active
Last reviewed	2026-07-10