Claiming

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

Registration only announces a cluster: it is created with the status Creating, owned by nobody. Anyone could announce any domain, so ownership needs proof. The dashboard’s Claim page offers three proofs, and a fourth path skips the claim entirely:

Proof	What it needs	When to use it
Claim key (fingerprint tab)	The fingerprint lo kubehz register printed.	The usual case: you provisioned with HCLOUD_TOKEN in your shell.
Claim code	The heartbeat agent installed.	Any cluster, any provider; no Hetzner project involved.
By agent (nonce)	The heartbeat agent installed, plus one lo command.	You are at the CLI anyway and want the dashboard to watch the agent confirm.
Direct attribution	KUBEHZ_TOKEN in your shell at registration.	CI and automation. The cluster registers straight onto your tenant; there is nothing to claim.

Option 1: the claim key (usual)

When HCLOUD_TOKEN is set, lo kubehz register asks the api for a claim key and uploads its public half to your Hetzner Cloud project under the name kubehz-claim-<domain>. Only the project owner can hold that key, so its fingerprint is the proof. No token is pasted anywhere.

1. Open the dashboard at app.kubehz.cloud and sign in
2. Go to the Claim page and pick the SSH fingerprint tab
3. Paste the fingerprint from the CLI output: MD5:aa:bb:cc:… or the bare aa:bb:cc:… form (both are accepted)
4. Click Claim Cluster

kubehz matches the fingerprint against the claim key it minted for that cluster. On success the cluster attaches to your tenant and its detail page opens. The same check is available from a script:

curl -X POST https://api.kubehz.cloud/api/claims/verify \
  -H "Authorization: Bearer $KUBEHZ_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"fingerprint":"aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99"}'

The fingerprint is listed in the Hetzner Console under Security → SSH keys if you lose the CLI output. Re-running lo kubehz register rotates the key and prints the new fingerprint.

Legacy: the provisioning key

A cluster registered without HCLOUD_TOKEN is announced with the MD5 fingerprint of the SSH key in your provider descriptor (sshPublicKey). If that key exists in your Hetzner Cloud project, the same fingerprint tab accepts it. Recompute it at any time:

# the key named by sshPublicKey in your provider descriptor
ssh-keygen -E md5 -lf ~/.ssh/id_ed25519.pub

Option 2: the claim code

Needs the heartbeat agent installed: it mints the code on its first run. If lo kubehz claim-code prints nothing, the agent has not run yet.

The agent mints a one-time claim code inside your cluster on its first run. Print it with lo kubehz claim-code (pointed at that cluster). Then claiming is a single paste:

1. Open the dashboard at app.kubehz.cloud and sign in
2. Go to the Claim page and pick the Claim code tab
3. Paste the claim code, and you are 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 project, 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 claim key above.
• Minted once: the agent generates the code on its first run and never rotates it, so lo kubehz claim-code keeps printing the same code until it is used.

Option 3: by agent (nonce)

Also needs the heartbeat agent. Here the dashboard mints the secret and your cluster echoes it back:

1. On the Claim page pick By agent. The dashboard mints a challenge nonce (khzn_…) and waits.

2. Place it in your cluster with the CLI:

   lo kubehz claim --nonce khzn_...

3. The agent echoes the nonce in its next heartbeat. The dashboard sees it and attaches the cluster to your tenant.

The nonce is single-use and short-lived; if the page times out, mint a new one.

Option 4: no claim at all

With KUBEHZ_TOKEN in your shell (a clusters:write API token from the dashboard, Access → API Tokens), lo kubehz register registers the cluster directly on your tenant. It appears in your cluster list at once; there is no claim step. This is the path for CI. Keep the token in a secret store, never in the spec.

Security notes

• A fingerprint is public information: it identifies a public key but cannot impersonate you. The claim key works because only your Hetzner project can hold the key kubehz minted for your cluster.
• The platform never connects into your cluster. Health data flows outbound-only, via the heartbeat agent.
• If verification fails, the dashboard reports it (“Claim verification failed”) and nothing is attached.

After claiming

• The cluster leaves Creating 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
Fingerprint not accepted	Use the fingerprint lo kubehz register printed, or read it from the Hetzner Console (Security → SSH keys, key kubehz-claim-<domain>). Re-run lo kubehz register with HCLOUD_TOKEN set to mint a fresh key
Claim code “not found”	Codes are one-time and expire with the registration. Use the claim key
The “By agent” page keeps waiting	The agent has not beaten since you placed the nonce. Check kubectl -n kubehz-system get cronjob kubehz-heartbeat, then mint a new nonce
Key missing from Hetzner	lo kubehz register could not upload the claim key. Check that HCLOUD_TOKEN has Read & Write permission on the project, then re-run 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
Last reviewed	5 September 2026