Skip to main content
Selbstgehostete Umgebungen befinden sich in der öffentlichen Beta für Team- und Enterprise-Pläne; Verfügbarkeit und Einschränkungen behandelt den Aktivierungspfad. Diese Seite bringt Ihre erste Sitzung zum Laufen; siehe Selbstgehostete Umgebungen für deren Funktionsweise und Bereitstellung in der Produktion für Härtung und Fleet-Rezepte.
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.
  • Den GitHub-Konnektor, aktiviert durch einen Owner, sowie die eigene GitHub-Verbindung jedes Entwicklers, damit Entwickler github.com-Repositorys 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. Ein SSH-Schlüssel allein reicht nicht aus, da der Runner die https://-URL des Repositorys klont. Um stattdessen über SSH zu klonen, siehe Git-URLs für private Netzwerke umschreiben.
  • 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. Ein Runner, der Sitzungen von Claude Tag bedient, benötigt v2.1.229 oder später sowie python3 in seinem PATH, da die Hooks, die die Control Plane für diese Sitzungen bereitstellt, python3 ausführen. 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:
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. Wenn Sie diese Ausgabe sehen, aktualisieren Sie Claude Code. Wenn Sie claude aus einem Container-Image ausführen, erstellen Sie das Image neu, mit Version 2.1.224 oder später.

​
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:
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.
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.
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.
Verwenden Sie ein Verzeichnis, das ausschließlich für den Runner bestimmt ist, nicht Ihr Home-Verzeichnis oder ein Verzeichnis mit Ihren eigenen Klonen. Der Runner behandelt alles, was er unter <writable-dir>/<repo-owner>/<repo> vorfindet, als seinen eigenen Klon und kann ihn zurücksetzen sowie Dateien darin überschreiben oder löschen.
Wenn der Runner das Basisverzeichnis nicht erstellen oder nicht hineinschreiben kann, beendet er sich beim Start mit einem Fehler, der das Verzeichnis benennt, statt sich zu registrieren. Siehe Fehlerbehebung.Starten Sie dann den Runner mit --environment-secret-file und --base-dir:
Der Runner protokolliert Registered: runner_id=<runner-id>, sobald er sich bei Ihrer Umgebung registriert hat, und beginnt dann, nach Arbeit abzufragen. Mit diesem Befehl gestartet, beendet er sich absichtlich, nachdem er eine Sitzung bedient hat, nicht nach jedem Turn. Um weitere Sitzungen zu bedienen, starten Sie den Runner jedes Mal erneut, wenn er sich beendet. Unter Wenn der Runner sich beendet erfahren Sie, wann das passiert und was der Runner protokolliert.
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 über seine HTTPS-URL klonen kann, ohne nach Anmeldedaten gefragt zu werden.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: Wenn der Fehler 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.
    • HTTPS-Anmeldedaten bereitstellen: Siehe Git konfigurieren
    • Stattdessen über SSH klonen: Wenn der Runner-Host bereits einen SSH-Schlüssel hat, siehe Git-URLs für private Netzwerke umschreiben
    • Nach einer der beiden Korrekturen: Starten Sie den Runner erneut und beobachten Sie die fehlgeschlagene Sitzung, statt eine neue zu starten. Wenn sie mehrmals fehlgeschlagen ist, warten Sie einige Minuten, bis der Runner Picked up session protokolliert.
    • Um stattdessen ein anderes Repository zu verwenden: Archivieren oder löschen Sie die fehlgeschlagene Sitzung, starten Sie dann den Runner erneut und starten Sie eine neue Sitzung. Andernfalls kann der Runner die fehlgeschlagene Sitzung statt der neuen aufnehmen.

​
Wenn der Runner sich beendet

Wenn der Runner sich während dieses Schnellstarts beendet, starten Sie ihn erneut. Der Runner kann sich von selbst beenden:
  • Nichts mehr aktiv: Das Log zeigt [runner:exit] account workload drained — exiting. Der Runner beendet sich absichtlich, sobald er keine Sitzung mehr ausführt, zum Beispiel:
    • Sie haben die Sitzung archiviert oder gelöscht: Starten Sie den Runner erneut
    • Die Sitzung konnte nicht gestartet werden: Beheben Sie die Ursache und starten Sie den Runner dann erneut
  • 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:
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