SpyBara
Go Premium

self-hosted-environments-quickstart.md 2026-10-09 23:02 UTC to 2026-10-10 18:02 UTC

This page contains 45 additions and 7 deletions.

2026
Sun 4 23:58 Sat 10 18:58

Schnellstart für selbstgehostete Umgebungen

Richten Sie Ihre erste selbstgehostete Umgebung ein: Installieren Sie Claude Code, erstellen Sie die Umgebung, starten Sie einen Runner und leiten Sie eine Sitzung dorthin weiter.

Eine selbstgehostete Umgebung führt Claude Code Cloud-Sitzungen auf einer Infrastruktur aus, die Ihre Organisation betreibt, ausgeführt durch Runner-Prozesse, die Sie bereitstellen. Dieser Schnellstart richtet Ihre erste ein, die kleinste, die funktioniert: ein Runner auf einem einzelnen Host, der eine Test-Sitzung ausführt. Es gibt zwei Schritte: erstellen Sie die Umgebung, starten Sie einen Runner und leiten Sie eine Sitzung dorthin weiter, dann senden Sie eine Nachricht an diese Sitzung von Ihrem Terminal. Sie werden zwischen zwei Oberflächen wechseln: claude.ai zum Erstellen der Umgebung, Überprüfen ihres Status und Weiterleiten einer Sitzung, und ein Terminal auf dem Host für alles, was der Runner tut.

Am Ende haben Sie eine Umgebung auf der Cloud-Umgebungen Admin-Seite, einen Runner, der auf Arbeit wartet, und eine Sitzung, die auf Ihrem Host läuft. Bevor Sie echte Repositories oder interne Systeme verbinden, arbeiten Sie Bereitstellung in der Produktion durch, die die Sicherheitslage, Egress-Kontrolle, Git-Anmeldedaten und Orchestrierung behandelt.

Voraussetzungen

Organisation und Rollen

Die claude.ai-Seite benötigt:

  • Selbstgehostete Umgebungen zulassen aktiviert durch einen Owner auf der Cloud-Umgebungen Admin-Seite; die Schaltfläche Neu wird erst angezeigt, wenn dies der Fall ist. Wenn Sie diese Rolle nicht haben, kann jemand, der sie hat, die Umgebung erstellen und Ihnen ihr Geheimnis übergeben; die Runner- und Terminal-Schritte auf dieser Seite benötigen keine claude.ai-Rolle, und wo ein Schritt den Status in der Admin-Benutzeroberfläche überprüft, geben Ihnen die eigenen Protokollzeilen des Runners das gleiche Signal.
  • Eine GitHub-Verbindung für Ihre Organisation, damit Entwickler Repositories auswählen können, wenn sie Sitzungen starten.

Host und Netzwerk

Der Runner-Host benötigt:

  • Einen Linux- oder macOS-Host oder Container mit ausgehendem HTTPS zu api.anthropic.com, zu claude.ai und den Download-Hosts, auf die es für den Installationsschritt unten umleitet, und zu Ihrem Git-Host für den Klon; die Netzwerkanforderungstabelle hat die vollständige Liste. Windows wird nicht als Runner-Host unterstützt; führen Sie den Runner stattdessen in einem Linux-Container aus. Entwickler-Workstations sind nicht betroffen, da Sitzungen von claude.ai in einem Browser aus gestartet werden.
  • Ein Repository für die Testsitzung: ein öffentliches oder eines, das dieser Host bereits über seine HTTPS-URL klonen kann, ohne nach Anmeldedaten gefragt zu werden.
  • Eine Uhr, die mit der Realzeit synchronisiert ist, beispielsweise mit NTP. Die Authentifizierung schlägt fehl, wenn die Uhr um mehr als fünf Minuten abweicht; siehe Troubleshooting.

Software auf dem Runner-Host

Installieren Sie auf dem Host, bevor Sie beginnen:

  • Claude Code v2.1.224 oder später, mit einer der Standard-Installationsmethoden. Der Runner ist Teil der Standard-claude-Binärdatei, und frühere Versionen erkennen den self-hosted-runner-Unterbefehl nicht. Der native Installer's Standard-latest-Kanal trägt jede Version, sobald sie veröffentlicht wird; der stable-Kanal, das Homebrew claude-code-Cask und die stabilen apt-, dnf- und apk-Repositories liegen etwa eine Woche hinterher. Um die genaue Version zu fixieren, die Ihre Fleet ausführt, siehe Installieren Sie eine bestimmte Version. Für Container-Images siehe die Dockerfile in Bereitstellung in der Produktion.
  • Git 2.24 oder neuer. Einige Git-Optionen auf der Deploy-Seite benötigen neuere Versionen; Git konfigurieren gibt jede Untergrenze an.

Bestätigen Sie, dass der Host bereit ist:

claude self-hosted-runner --help

Ein bereiter Host gibt den Verwendungstext des Runners aus und listet Flags wie --environment-secret-file auf. Bei Versionen älter als 2.1.224 gibt der Befehl stattdessen die allgemeine claude --help-Ausgabe aus; aktualisieren Sie mit claude update oder installieren Sie neu vom latest-Kanal.

Richten Sie eine Umgebung und einen Runner ein

Verwenden Sie entweder das geführte Setup oder die manuellen Schritte. Das geführte Setup ist ein einzelner Befehl, der eine interaktive Claude Code-Sitzung startet und Sie durch den Rest führt. Verwenden Sie stattdessen die manuellen Schritte auf einem Host, auf dem eine interaktive Sitzung nicht möglich ist. Verwenden Sie sie auch, wenn jemand mit der Owner-Rolle die Umgebung erstellt und Ihnen ihr Geheimnis übergeben hat, da das geführte Setup eine Owner-Anmeldung erfordert.

Geführtes Setup ausführen

Das geführte Setup führt Sie durch das Erstellen der Umgebung in der Admin-Benutzeroberfläche, startet einen lokalen Runner mit der Geheimnis-Datei, die Sie speichern, bestätigt, dass sich der Runner registriert, und schreibt einen Spickzettel nach ./runner-setup/CHEAT-SHEET.md. Bevor Sie es ausführen, überprüfen Sie Ihre Anmeldung und Version:

  • Anmeldung: Führen Sie es auf einem Computer aus, auf dem Sie sich mit claude auth login mit einem Konto angemeldet haben, das eine Owner-Rolle hat. Mit nur einem API-Schlüssel oder einem Drittanbieter-Modellanbieter startet die Sitzung, aber ihre Organisationsprüfungen schlagen fehl.
  • Version: Bestätigen Sie, dass die Versionsüberprüfung bestanden wurde. Bei Versionen älter als 2.1.224 startet der Setup-Befehl eine Claude-Sitzung mit den Wörtern als Prompt statt des geführten Setups.

Um das geführte Setup zu starten, führen Sie den Setup-Unterbefehl in Ihrer Shell aus und folgen Sie den Anweisungen:

claude self-hosted-runner setup

Das Setup startet selbst keine Test-Sitzung: Es fordert Sie auf, eine unter claude.ai/code zu starten. Der letzte Schritt des Setups stoppt den Runner, den es gestartet hat. Wenn Sie das Setup vor diesem Schritt verlassen, läuft der Runner weiter. Um nach dem letzten Schritt weiterzumachen, starten Sie den Runner in Ihrer Shell erneut mit dem Befehl in ./runner-setup/CHEAT-SHEET.md und leiten Sie dann eine Sitzung zur Umgebung weiter.

Manuell einrichten

Erstellen Sie die Umgebung auf claude.ai, starten Sie den Runner über ein Terminal auf dem Host und kehren Sie dann zu claude.ai zurück, um zu bestätigen, dass der Runner angezeigt wird, und eine Sitzung an ihn weiterzuleiten. Wenn jemand mit der Owner-Rolle die Umgebung bereits erstellt und Ihnen ihr Geheimnis übergeben hat, beginnen Sie bei Schritt 2.

1

Erstellen Sie eine Umgebung

Gehen Sie zur Cloud-Umgebungen Seite in den Admin-Einstellungen. Wählen Sie unter Selbstgehostete Umgebungen die Option Neu, benennen Sie die Umgebung und wählen Sie Erstellen. Wählen Sie im zweiten Schritt des Assistenten Umgebungsschlüssel kopieren, um das Umgebungsgeheimnis zu kopieren, das die Admin-Benutzeroberfläche als Umgebungsschlüssel bezeichnet. claude.ai zeigt das Geheimnis einmal an, und Sie können es später nicht abrufen; es läuft 365 Tage nach der Erstellung ab. Die ccpool_...-ID der Umgebung bleibt in ihrem Detaildialog sichtbar; Sie benötigen sie für die aud-Überprüfung in Token-Verifizierung und zum Versenden von Test-Sitzungen aus CI.

Wenn Sie das Geheimnis verlieren oder es rotieren müssen, erstellen Sie ein neues Geheimnis auf der Registerkarte Konfiguration der Umgebung, rollen Sie das neue Geheimnis auf Ihren Runnern aus und widerrufen Sie dann das alte. Runner, die ein widerrufenes Geheimnis halten, schlagen ihre nächste authentifizierte Abfrage fehl und beenden sich, protokollieren poll auth failed, und Ihr Orchestrator startet sie mit dem neuen Geheimnis neu.

2

Starten Sie einen Runner

Erstellen Sie das Geheimnis-Verzeichnis. Dieser Befehl und der nächste verwenden /etc/claude, was Root-Rechte erfordert, und die Geheimnis-Datei, die sie erstellen, ist nur für den Benutzer lesbar, der sie ausführt. Wenn der Runner als anderer Benutzer ausgeführt wird, beendet er sich mit error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>'). Führen Sie in diesem Fall beide Befehle als Benutzer des Runners aus, mit einem Verzeichnis anstelle von /etc/claude, in das dieser Benutzer schreiben kann, und übergeben Sie denselben Pfad an --environment-secret-file. Jeder Pfad, den der Runner-Prozess lesen kann, funktioniert.

mkdir -p /etc/claude

Schreiben Sie das Umgebungsgeheimnis in eine Datei. Der Befehl unten liest von Ihrem Terminal, damit das Geheimnis aus der Shell-Historie bleibt: Fügen Sie den Wert ein, den Sie kopiert haben, drücken Sie Enter, dann Strg-D, und die umask der Subshell macht die Datei nur für ihren Besitzer lesbar.

(umask 077 && cat > /etc/claude/environment-secret)

Wählen Sie ein Basisverzeichnis und ersetzen Sie <writable-dir> im Runner-Befehl unten durch einen absoluten Pfad, in den der Runner schreiben oder erstellen kann. Der Runner erstellt das Verzeichnis beim Start, überprüft dann Repositories aus und erstellt Pro-Sitzungs-Verzeichnisse darunter. Ohne --base-dir verwendet er /workspace, was nur funktioniert, wenn dieses Verzeichnis bereits existiert und beschreibbar ist oder Sie den Runner als Root starten.

Wenn der Runner nicht in den Pfad erstellen oder schreiben kann, beendet er sich beim Start mit einem Fehler, der das Verzeichnis benennt, statt sich zu registrieren. Siehe Troubleshooting.

Starten Sie dann den Runner mit --environment-secret-file und --base-dir:

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

Der Runner protokolliert Registered: runner_id=<runner-id>, sobald er sich bei Ihrer Umgebung registriert hat, und beginnt dann, nach Arbeit abzufragen. Wenn der Runner sich später beendet, starten Sie ihn selbst neu. Unter Wenn der Runner sich beendet erfahren Sie, wann das passiert.

3

Überprüfen Sie, ob der Runner angezeigt wird

Kehren Sie zur Cloud-Umgebungen Seite zurück. Der Status Ihrer Umgebung ändert sich innerhalb weniger Sekunden nach dem Start des Runners von Keine Runner bereitgestellt zu Healthy; öffnen Sie die Umgebung und wählen Sie Aktivität, um den Runner selbst zu sehen. Wenn Sie keinen Zugriff auf die Admin-Seite haben, liefert Ihnen die Zeile Registered: runner_id=<runner-id> im Log des Runners aus dem vorherigen Schritt dasselbe Signal.

4

Leiten Sie eine Sitzung zur Umgebung weiter

Starten Sie eine Sitzung unter claude.ai/code und wählen Sie Ihre Umgebung aus dem Umgebungs-Picker, wo selbstgehostete Umgebungen neben von Anthropic gehosteten angezeigt werden. Wählen Sie als Repository dasjenige aus den Voraussetzungen: ein öffentliches Repository oder eines, das dieser Host bereits klonen kann. Der Runner klont mit den Git-Anmeldedaten, die der Host bereits hat.

Der nächste verfügbare Runner nimmt die wartende Sitzung auf und protokolliert Picked up session <session-id> zusammen mit seiner aktiven Anzahl und Kapazität, damit Sie aus der eigenen Ausgabe des Runners bestätigen können, welcher Host die Sitzung übernommen hat. Beobachten Sie die Sitzungsarbeit und lesen Sie Claudes Antworten unter claude.ai/code.

Wenn die Sitzung nicht mit der Arbeit beginnt, orientieren Sie sich an dem, was Sie sehen:

  • Die Sitzung bleibt in der Warteschlange: Siehe Fehlerbehebung.
  • Die Sitzung startet nicht und zeigt einen Git-Fehler: Der Fehler erscheint in der Sitzung und im Log des Runners. Wenn er Gits could not read Username for gefolgt von der URL Ihres Git-Hosts enthält, hatte der Runner keine HTTPS-Anmeldedaten für diesen Host. Siehe Git konfigurieren, wo auch Anmeldedaten-Optionen für private Repositorys in der Produktion behandelt werden.

Wenn der Runner sich beendet

Wenn der Runner sich während dieses Schnellstarts beendet, starten Sie ihn mit demselben Befehl erneut. Der Runner kann sich von selbst beenden:

  • Sitzungen abgeschlossen: Das Log zeigt [runner:exit] account workload drained — exiting. Der Runner beendet sich absichtlich, sobald seine aktiven Sitzungen abgeschlossen sind. Siehe Runner-Lebenszyklus.
  • Verbindung verloren: Das Log zeigt eine [runner:fatal]-Zeile mit runner record gone server-side oder mit poll auth failed. Wenn der Runner für eine Weile den Kontakt zu Anthropic verliert, zum Beispiel weil der Host in den Ruhezustand wechselt, kann er sich beenden, sobald er Anthropic das nächste Mal erreicht.

Ein abgeschlossener Turn beendet Ihre Test-Sitzung nicht. Nach dem ersten Turn ist die Sitzung noch verbunden und der Runner läuft noch, sodass Sie der Sitzung eine Folgenachricht senden können, ohne den Runner zuerst neu zu starten.

Für die Produktion stellen Sie den Runner unter einem Orchestrator bereit, der ihn beim Beenden neu startet und länger zwischen Neustarts wartet, wenn der Runner sich kurz nach dem Start immer wieder beendet. Siehe Bereitstellung in der Produktion und Wenn der Runner beendet wird.

Senden Sie eine Nachricht an eine laufende Sitzung

Sobald eine Sitzung in Ihrer Umgebung läuft, senden Sie ihr eine Nachricht von der claude CLI auf einem beliebigen Computer, auf dem Sie sich mit claude auth login angemeldet haben; der Befehl muss nicht auf dem Computer ausgeführt werden, der die Sitzung gestartet hat. Der Befehl sendet eine Nachricht:

claude -p "your message" --cloud <session-id>

Für <session-id> übergeben Sie die bloße session_... oder cse_...-ID oder die claude.ai/code-URL der Sitzung. Ein erfolgreicher Versand gibt Sent to cloud session. mit der Sitzungs-ID und einem Ansicht-Link aus. Akzeptierte ID-Formate, JSON-Ausgabe sowie die Konto- und Richtlinienanforderungen finden Sie unter Senden Sie Nachfolgen von der CLI, da der Befehl bei von Anthropic gehosteten Sitzungen genauso funktioniert.

Was kommt als Nächstes

  • Bereitstellung in der Produktion: Härtung der Bereitstellung, Kontrolle des Egress, Konfiguration von Git-Anmeldedaten und Ausführung der Fleet unter Kubernetes oder Compose
  • Passen Sie Sitzungen an: Wrapper-Skripte, Lifecycle-Hooks, On-Demand-Runner, MCP-Server und Berechtigungen
  • Testen Sie End-to-End: ein CI-Smoke-Test, der eine Sitzung versendet und Claudes Antworten liest