Agent keys

An agent key is a sign-in for a machine: an AI agent, a CI job or a script. The key works with the kubehz API, with kubectl on your hosted clusters and Spaces, and with the MCP server. It is a client ID and a client secret. It never uses your password, and every key expires.

An AI app such as Claude or ChatGPT can also act as you, without a key. See Connect an app as yourself.

Create a key

You need the role Owner or Admin in the tenant. A tenant can have at most 25 active keys.

1. In the dashboard, open Access → Agent keys.
2. Click New agent key.
3. In Name, type a name of at most 64 characters, for example ci-agent.
4. Under Role, select Viewer, Editor or Admin.
5. Under Scope, select Chosen clusters and spaces or Whole tenant.
6. If you selected Chosen clusters and spaces, tick the clusters and Spaces that the key can reach.
7. In Expires after (days), type a number from 1 to 90. The default is 30.
8. Optional: in Monthly spend cap in euros (optional), type a cap.
9. Click Create key.
10. If a sign-in window opens, confirm with your second factor.
11. Copy the Client secret and the block Environment for lo kubehz token. kubehz shows the secret only this one time.
12. Click I’ve stored it.

Role

Role	On the kubehz API	Inside clusters and Spaces
Viewer	Reads clusters and Spaces	Reads, without Secrets
Editor	Also creates, changes and deletes clusters and Spaces	Reads and writes most resources
Admin	Like Editor. Also reads the audit log and billing, and can connect the Hetzner Cloud token	Full control, also over Secrets and RBAC

Scope

• Chosen clusters and spaces is the default. The key reaches only the clusters and Spaces that you tick, at most 50 of each. It also reaches what it creates itself. If you tick nothing, the key reaches only what it creates.
• Whole tenant: the key reaches every cluster and Space of the tenant, also the ones that someone creates later.

Spend cap

The cap counts the cost of the clusters and Spaces that the key created, per calendar month (UTC). When the cost reaches the cap, the key cannot create a cluster or a Space, extend a lease or change a cluster. What already runs keeps running and costs money until someone deletes it or its lease ends. Thus the cap stops new spend. It is not a hard limit.

• The count uses the full price, without a free allowance or a discount.
• The count can be up to one hour behind.
• The count starts again on the 1st of each month (UTC).
• The cap is from 1 to 100,000 euros. Leave the field empty for no cap.

Use the key with kubectl

The agent kubeconfig works on hosted clusters and on Spaces. A self-hosted cluster has its own RBAC. The key reaches it only through the kubehz API.

You need lo, the CLI of lok8s, on the machine that runs kubectl.

1. Open the page of the hosted cluster or the Space.
2. Click Download agent kubeconfig.
3. Save the file as agent.kubeconfig.
4. Set the four variables from the block Environment for lo kubehz token.
5. Run kubectl with the file.

export KUBEHZ_AGENT_CLIENT_ID='...'
export KUBEHZ_AGENT_CLIENT_SECRET='...'
export KUBEHZ_AGENT_TOKEN_URL='https://id.kubehz.cloud/oauth/v2/token'
export KUBEHZ_AGENT_SCOPE='...'
kubectl --kubeconfig agent.kubeconfig get pods

The file holds no secret. kubectl runs lo kubehz token, which gets a token with the key. lo keeps the token until five minutes before it expires, so a kubectl call does not cost a new sign-in.

Use the key with the API

lo kubehz token --format token prints only the token:

TOKEN=$(lo kubehz token --format token)
curl -s -H "Authorization: Bearer $TOKEN" https://api.kubehz.cloud/api/agent-keys/self

Without lo, use the OAuth client-credentials grant:

TOKEN=$(curl -s -u "$KUBEHZ_AGENT_CLIENT_ID:$KUBEHZ_AGENT_CLIENT_SECRET" \
  -d grant_type=client_credentials --data-urlencode "scope=$KUBEHZ_AGENT_SCOPE" \
  "$KUBEHZ_AGENT_TOKEN_URL" | jq -r .access_token)

GET /api/agent-keys/self shows the role, the scope and the expiry of the key, and its spend this month with its cap. For a key with Chosen clusters and spaces, it also lists the clusters and Spaces that the key reaches.

Leases: what an agent creates ends on its own

A Space or a hosted cluster that an agent key creates always has a lease. The lease is two hours, or the hours that the create names (leaseHours, 1 to 720). When the lease ends, kubehz deletes the Space or the cluster. Thus an agent that stops or forgets cannot leave a cluster that runs and costs money.

• To extend the lease, the agent sends PATCH /api/spaces/{id}/lease or PATCH /api/clusters/{id}/lease with {"hours": 24}. The new end is 24 hours from now.
• Extend the lease before it ends. After the end, kubehz refuses every change, also an extension (LEASE_ENDED). You can still read or delete the Space or the cluster. kubehz deletes it in a few minutes.
• An agent key cannot remove a lease. A person with the role Owner or Admin can. For a Space, click Remove lease on its page. For a hosted cluster, send {"hours": null} to the API.
• A person who sets a lease, or brings its end closer, confirms with the second factor. To extend or remove a lease needs no second factor.
• A lease of more than six hours gets one e-mail about one hour before it ends. The e-mail goes to the tenant owner. To stop it, switch off Lease ends soon in Settings → Notifications.
• A self-hosted cluster never has a lease. kubehz does not end what runs on your own Hetzner account.

On the page of a Space with a lease, the Lease card shows the end. To set a new end, type the hours in Hours from now, then click Extend lease.

What a key cannot do

• Create agent keys or API tokens, manage members, or switch AI apps on or off.
• Remove a lease.
• With the role Viewer: change a cluster or a Space.
• With the role Viewer or Editor: read the audit log or billing, or connect the Hetzner Cloud token.
• With Chosen clusters and spaces: see other clusters and Spaces, or read data of the whole tenant, for example its costs.
• Use kubectl on a self-hosted cluster.

Revoke a key

1. Open Access → Agent keys.
2. On the row of the key, click Revoke.
3. In the dialog, click Revoke.

The kubehz API refuses the key at once. The MCP server also refuses it, because each tool call goes through the API. A token that the agent already has still works on clusters and Spaces until it expires, at most 12 hours. You cannot undo a revoke.

A key also ends on its expiry date. The list warns 14 days before the end, and again 3 days before.