Eine Maschine aktivieren

Aktualisiert am 10. November 2026

Die Aktivierung verknüpft die Maschine mit Ihrem Konto, wie bei Claude Code oder einem Smart-TV: Die Maschine zeigt einen Code an, Sie geben ihn auf einem Gerät frei, auf dem Sie bereits angemeldet sind. Auf der Maschine wird kein Passwort eingegeben, und die Maschine erhält nie den Schlüssel Ihres Tresors.

Vorbereitung

  • Der Tarif Studio (oder seine Testphase) ist für das Konto aktiv.
  • Die Zwei-Faktor-Authentifizierung (TOTP) oder ein Passkey ist unter Sicherheit eingerichtet: Die Freigabe einer Maschine verlangt immer einen zweiten Faktor. Ohne beides wird die Freigabe mit einem Hinweis abgelehnt, einen davon einzurichten.
  • Ein Gerät mit geöffnetem Tresor: die Konsolity-App (Mac, Windows, Linux, iPhone, iPad, Android) oder die Webkonsole app.konsolity.com.

Die Aktivierung starten

Auf der Maschine, mit dem Benutzerkonto, das die CLI verwenden wird (für einen Dienst dasselbe Konto wie der Dienst):

konsolity login --name build-01
Option Funktion
--name <name> Name in der Liste der Maschinen (Standard: der Hostname).
--scopes <list> Angefragter Bereich, aus hosts, snippets, sessions, mcp, durch Kommas getrennt.
--read-only Fordert reinen Lesezugriff an (Listen und Status, kein Befehl).

Der angefragte Bereich ist nur ein Vorschlag: Sie legen ihn bei der Freigabe fest. Der Befehl zeigt an:

Activating this machine on https://api.konsolity.com
1. Open this address on a device signed in to your account:
   https://app.konsolity.com/cli/activate?code=WDJB-MJHT
   or in the Konsolity app: Settings › CLI machines › Activate a machine
2. Enter this code: WDJB-MJHT
3. Check that the fingerprint shown is: 7K3Q-9XAD
Waiting for approval...

Wenn das Terminal es erlaubt, wird zusätzlich ein QR-Code des vollständigen Links angezeigt, praktisch für die Freigabe vom Telefon aus. Der Code bleibt 15 Minuten gültig; die Maschine wartet und tut nichts anderes.

Den Fingerabdruck vergleichen

Der Fingerabdruck (im Beispiel 7K3Q-9XAD) wird aus dem öffentlichen Schlüssel berechnet, den die Maschine gerade erzeugt hat. Der Freigabebildschirm berechnet ihn selbst aus diesem Schlüssel neu, ohne dem Server zu vertrauen, und zeigt ihn zusammen mit Name, System, Architektur, Hostname und IP-Adresse der Maschine an.

Geben Sie nur frei, wenn Sie konsolity login gerade selbst auf dieser Maschine ausgeführt haben und der Fingerabdruck identisch ist. Eine Anfrage, die Sie nicht erkennen, lehnen Sie mit einem Klick ab.

In der App freigeben

In Konsolity: Einstellungen › CLI-Maschinen › Maschine aktivieren, dann den Code eingeben. Der Tresor muss geöffnet sein.

Im Browser freigeben

Öffnen Sie https://app.konsolity.com/cli/activate (oder den vollständigen Link, den die Maschine anzeigt), melden Sie sich an und geben Sie den Code ein. Die Seite fragt nach Ihrem Master-Passwort, um den Tresor im Browser zu öffnen: Es verlässt die Seite nie und wird nie an den Server gesendet.

Bereich und Ablaufzeit wählen

Vor der Freigabe wählen Sie:

  • den Bereich: hosts, snippets, sessions, mcp, nur lesend oder vollständig;
  • die Hosts und Snippets, die die Maschine verwenden darf (Standard: kein Host);
  • die Befehlsregeln (bei vollem Zugriff);
  • die Ablaufzeit der Maschine.

Standard: hosts und snippets, nur lesend, kein Host. Die Details stehen unter Bereich und Regeln.

Ablaufzeit Typische Verwendung
1 Tag Einmaliger Eingriff
7 Tage Kurzer Einsatz, Testserver
30 Tage Laufendes Projekt
90 Tage (Standard) Administrationsserver
1 Jahr Langlebige Maschine, jedes Jahr erneuert
Nie Nur für Maschinen, die Sie genau überwachen

Mit dem zweiten Faktor bestätigen

Die Schaltfläche Freigeben fragt nach Ihrem TOTP-Code oder Ihrem Passkey (Face ID, Touch ID, Windows Hello, Sicherheitsschlüssel). Der Server prüft den zweiten Faktor in derselben Anfrage wie die Freigabe: Ein gestohlener Code oder eine offen gelassene Sitzung reicht nicht aus.

Was bei der Freigabe passiert

  1. Ihr Gerät erzeugt einen zufälligen Maschinenschlüssel und versiegelt ihn für den öffentlichen Schlüssel der Maschine (X25519-Austausch). Der Server transportiert nur einen undurchsichtigen Block, den er nicht öffnen kann.
  2. Es kopiert, mit diesem Maschinenschlüssel verschlüsselt, nur die Hosts, Identitäten, SSH-Schlüssel, fixierten Host-Schlüssel und Snippets, die der Bereich erlaubt, zusammen mit den Regeln. Der Rest des Tresors verlässt Ihre Geräte nicht (siehe Bereich und Regeln).
  3. Die Maschine erhält ihr Token (einmalig), öffnet den Maschinenschlüssel, prüft, dass er ihre Regeln entschlüsselt, und legt Token und Schlüssel dann in ihrem geschützten Speicher ab (siehe Dienst und Speicherung).
  4. Sie erhalten eine E-Mail, eine App-Benachrichtigung und, falls verknüpft, eine Telegram-Nachricht „Neue CLI-Maschine“.

Der Befehl zeigt anschließend den Namen der Maschine und die E-Mail-Adresse des Kontos an. Den Status prüfen Sie jederzeit mit:

konsolity status

Eine Maschine pro Fingerabdruck

Jede Maschine hat einen Maschinen-Fingerabdruck, berechnet aus der Systemkennung (/etc/machine-id unter Linux, IOPlatformUUID unter macOS, MachineGuid unter Windows). Eine neue Aktivierung auf derselben Maschine ersetzt die vorherige: Der alte Eintrag wird automatisch widerrufen. Es gibt also nie zwei aktive Tokens für denselben Computer.

Dieser Fingerabdruck wird bei jedem Aufruf mitgesendet. Ein auf einen anderen Computer kopiertes Token wird abgelehnt, und das Ereignis löst eine Warnung aus.

setup-token: CI und Container

Ein CI-Runner oder ein Container wird oft jedes Mal neu erstellt: Seine Maschinenkennung ändert sich, und nichts lässt sich dauerhaft speichern. Für diese Fälle erstellen Sie ein langlebiges Token:

konsolity setup-token --name ci-deploy

Der Ablauf ist derselbe (Code, Fingerabdruck, Freigabe mit zweitem Faktor, Bereich). Am Ende zeigt der Befehl einmalig ein Token an, das mit ksetup_ beginnt, und schreibt nichts auf die Festplatte:

Long-lived token (shown once):
ksetup_3q2Xk...
Store it in your CI secret manager, then provide it through KONSOLITY_TOKEN.

Legen Sie es im Geheimnisspeicher Ihrer CI ab und übergeben Sie es dem Befehl über die Umgebungsvariable KONSOLITY_TOKEN:

KONSOLITY_TOKEN="$KONSOLITY_TOKEN" konsolity run web-01 -- systemctl status nginx

Ein langlebiges Token:

  • ist nicht an den Maschinen-Fingerabdruck gebunden (es dient flüchtigen Maschinen): Schützen Sie es wie ein Passwort;
  • muss ablaufen, spätestens 1 Jahr nach seiner Erstellung;
  • hat keine automatische Rotation;
  • erscheint in der Liste als Langlebiges Token, mit demselben Bereich, demselben Protokoll und demselben Widerruf wie eine Maschine.

Wenn es hakt

  • Code abgelaufen: Führen Sie konsolity login erneut aus, ein neuer Code wird erstellt.
  • Zweiter Faktor erforderlich: Richten Sie unter Sicherheit die Zwei-Faktor-Authentifizierung oder einen Passkey ein und beginnen Sie dann neu.
  • Abonnement erforderlich: Die Freigabe erfordert den Tarif Studio (oder seine Testphase).
  • Abgelehnt: Die Maschine beendet sich, ohne etwas zu speichern.
  • Maschine bereits aktiviert: konsolity logout, dann konsolity login.