Agent-Schlüssel

Ein Agent-Schlüssel ist eine Anmeldung für eine Maschine: einen KI-Agenten, einen CI-Job oder ein Skript. Der Schlüssel funktioniert mit der kubehz-API, mit kubectl auf deinen gehosteten Clustern und Spaces und mit dem MCP-Server. Er besteht aus einer Client-ID und einem Client-Secret. Er braucht nie dein Passwort, und jeder Schlüssel läuft ab.

Eine KI-App wie Claude oder ChatGPT kann auch ohne Schlüssel in deinem Namen handeln. Siehe Eine App in deinem Namen verbinden.

Einen Schlüssel erstellen

Du brauchst die Rolle Owner oder Admin im Mandanten. Ein Mandant kann höchstens 25 aktive Schlüssel haben.

1. Öffne im Dashboard Zugriff → Agent-Schlüssel.
2. Klicke auf Neuer Agent-Schlüssel.
3. Gib unter Name einen Namen mit höchstens 64 Zeichen ein, zum Beispiel ci-agent.
4. Wähle unter Rolle Betrachter, Bearbeiter oder Admin.
5. Wähle unter Bereich Gewählte Cluster und Spaces oder Ganzer Mandant.
6. Wenn du Gewählte Cluster und Spaces gewählt hast, kreuze die Cluster und Spaces an, die der Schlüssel erreichen soll.
7. Gib unter Läuft ab nach (Tagen) eine Zahl von 1 bis 90 ein. Der Standard ist 30.
8. Optional: Gib unter Monatliches Ausgabenlimit in Euro (optional) ein Limit ein.
9. Klicke auf Schlüssel erstellen.
10. Wenn sich ein Anmeldefenster öffnet, bestätige mit deinem zweiten Faktor.
11. Kopiere das Client-Secret und den Block Umgebung für lo kubehz token. kubehz zeigt das Secret nur dieses eine Mal.
12. Klicke auf Ich habe es gespeichert.

Rolle

Rolle	In der kubehz-API	In Clustern und Spaces
Betrachter	Liest Cluster und Spaces	Liest, ohne Secrets
Bearbeiter	Erstellt, ändert und löscht außerdem Cluster und Spaces	Liest und schreibt die meisten Ressourcen
Admin	Wie Bearbeiter. Liest außerdem das Audit-Log und die Abrechnung und kann das Hetzner-Cloud-Token verbinden	Volle Kontrolle, auch über Secrets und RBAC

Bereich

• Gewählte Cluster und Spaces ist der Standard. Der Schlüssel erreicht nur die Cluster und Spaces, die du ankreuzt, höchstens 50 von jeder Art. Er erreicht auch, was er selbst erstellt. Kreuzt du nichts an, erreicht der Schlüssel nur, was er selbst erstellt.
• Ganzer Mandant: Der Schlüssel erreicht alle Cluster und Spaces des Mandanten, auch die, die später jemand erstellt.

Ausgabenlimit

Das Limit zählt die Kosten der Cluster und Spaces, die der Schlüssel erstellt hat, pro Kalendermonat (UTC). Erreichen die Kosten das Limit, kann der Schlüssel keinen Cluster und keinen Space mehr erstellen, keine Laufzeit verlängern und keinen Cluster ändern. Was schon läuft, läuft weiter und kostet Geld, bis jemand es löscht oder seine Laufzeit endet. Das Limit stoppt also neue Ausgaben. Es ist keine harte Grenze.

• Die Zählung nutzt den vollen Preis, ohne Freikontingent und ohne Rabatt.
• Die Zählung kann bis zu einer Stunde hinterherhinken.
• Die Zählung beginnt am 1. jedes Monats (UTC) neu.
• Das Limit liegt zwischen 1 und 100.000 Euro. Lass das Feld leer für kein Limit.

Den Schlüssel mit kubectl nutzen

Die Agent-Kubeconfig funktioniert auf gehosteten Clustern und auf Spaces. Ein selbst gehosteter Cluster hat sein eigenes RBAC. Der Schlüssel erreicht ihn nur über die kubehz-API.

Du brauchst lo, die CLI von lok8s, auf der Maschine, auf der kubectl läuft.

1. Öffne die Seite des gehosteten Clusters oder des Spaces.
2. Klicke auf Agent-Kubeconfig herunterladen.
3. Speichere die Datei als agent.kubeconfig.
4. Setze die vier Variablen aus dem Block Umgebung für lo kubehz token.
5. Starte kubectl mit der Datei.

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

Die Datei enthält kein Secret. kubectl startet lo kubehz token, das mit dem Schlüssel ein Token holt. lo behält das Token bis fünf Minuten vor seinem Ablauf, damit nicht jeder kubectl-Aufruf eine neue Anmeldung kostet.

Den Schlüssel mit der API nutzen

lo kubehz token --format token gibt nur das Token aus:

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

Ohne lo nutzt du den 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 zeigt Rolle, Bereich und Ablauf des Schlüssels und seine Ausgaben in diesem Monat mit seinem Limit. Für einen Schlüssel mit Gewählte Cluster und Spaces listet es auch die Cluster und Spaces, die der Schlüssel erreicht.

Laufzeit: was ein Agent erstellt, endet von selbst

Ein Space oder ein gehosteter Cluster, den ein Agent-Schlüssel erstellt, hat immer eine Laufzeit. Sie beträgt zwei Stunden oder die Stunden, die das Erstellen nennt (leaseHours, 1 bis 720). Endet die Laufzeit, löscht kubehz den Space oder den Cluster. So kann ein Agent, der stoppt oder es vergisst, keinen Cluster zurücklassen, der läuft und Geld kostet.

• Um die Laufzeit zu verlängern, sendet der Agent PATCH /api/spaces/{id}/lease oder PATCH /api/clusters/{id}/lease mit {"hours": 24}. Das neue Ende liegt 24 Stunden ab jetzt.
• Verlängere die Laufzeit, bevor sie endet. Nach dem Ende lehnt kubehz jede Änderung ab, auch eine Verlängerung (LEASE_ENDED). Du kannst den Space oder den Cluster noch lesen oder löschen. kubehz löscht ihn nach wenigen Minuten.
• Ein Agent-Schlüssel kann eine Laufzeit nicht entfernen. Eine Person mit der Rolle Owner oder Admin kann es. Für einen Space klickst du auf seiner Seite auf Laufzeit entfernen. Für einen gehosteten Cluster sendest du {"hours": null} an die API.
• Wer als Person eine Laufzeit setzt oder ihr Ende vorzieht, bestätigt mit dem zweiten Faktor. Zum Verlängern oder Entfernen braucht es keinen zweiten Faktor.
• Eine Laufzeit von mehr als sechs Stunden bekommt eine E-Mail, etwa eine Stunde vor ihrem Ende. Die E-Mail geht an den Owner des Mandanten. Um sie abzustellen, schalte unter Einstellungen → Benachrichtigungen die Meldung Laufzeit endet bald aus.
• Ein selbst gehosteter Cluster hat nie eine Laufzeit. kubehz beendet nichts, was in deinem eigenen Hetzner-Konto läuft.

Auf der Seite eines Spaces mit Laufzeit zeigt die Karte Laufzeit das Ende. Um ein neues Ende zu setzen, gib die Stunden unter Stunden ab jetzt ein und klicke dann auf Laufzeit verlängern.

Was ein Schlüssel nicht kann

• Agent-Schlüssel oder API-Tokens erstellen, Mitglieder verwalten oder KI-Apps ein- oder ausschalten.
• Eine Laufzeit entfernen.
• Mit der Rolle Betrachter: einen Cluster oder einen Space ändern.
• Mit der Rolle Betrachter oder Bearbeiter: das Audit-Log oder die Abrechnung lesen oder das Hetzner-Cloud-Token verbinden.
• Mit Gewählte Cluster und Spaces: andere Cluster und Spaces sehen oder Daten des ganzen Mandanten lesen, zum Beispiel seine Kosten.
• kubectl auf einem selbst gehosteten Cluster nutzen.

Einen Schlüssel widerrufen

1. Öffne Zugriff → Agent-Schlüssel.
2. Klicke in der Zeile des Schlüssels auf Widerrufen.
3. Klicke im Dialog auf Widerrufen.

Die kubehz-API lehnt den Schlüssel sofort ab. Auch der MCP-Server lehnt ihn ab, denn jeder Tool-Aufruf geht über die API. Ein Token, das der Agent schon hat, funktioniert in Clustern und Spaces bis zu seinem Ablauf weiter, höchstens 12 Stunden. Einen Widerruf kannst du nicht rückgängig machen.

Ein Schlüssel endet außerdem an seinem Ablaufdatum. Die Liste warnt 14 Tage vor dem Ende und noch einmal 3 Tage davor.