SpyBara
Go Premium

self-hosted-environments.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 54 additions and 78 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Tue 6 23:59 Sat 10 23:01 Wed 14 22:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59 Sat 24 22:59 Thu 29 23:57 Fri 30 23:01

Selbst gehostete Umgebungen

Führen Sie Claude Code Cloud-Sitzungen auf einer Infrastruktur aus, die Sie kontrollieren: Richten Sie eine selbst gehostete Umgebung ein, stellen Sie Runner bereit und leiten Sie Sitzungen zu Ihrem eigenen Compute weiter.

[!NOTE]

Selbst gehostete Umgebungen befinden sich in der öffentlichen Beta für Team- und Enterprise-Pläne und sind standardmäßig deaktiviert. Siehe Verfügbarkeit und Einschränkungen für den Aktivierungspfad und was ausgeschlossen ist.

Eine selbst gehostete Umgebung führt Claude Code Cloud-Sitzungen auf einer Infrastruktur aus, die Ihre Organisation betreibt. Eine Cloud-Sitzung ist jede Sitzung, die irgendwo anders als auf dem Rechner des Entwicklers ausgeführt wird. Entwickler starten sie von claude.ai, den mobilen und Desktop-Apps, dem Terminal mit claude --cloud und geplanten Aufgaben in der Cloud. Standardmäßig werden Cloud-Sitzungen auf der Infrastruktur von Anthropic ausgeführt.

In einer selbst gehosteten Umgebung werden dieselben Sitzungen in Ihrem Netzwerk ausgeführt. Die Entwicklererfahrung ist ansonsten gleich, abgesehen von den Unterschieden in Verfügbarkeit und Einschränkungen und den bekannten Problemen der Bereitstellungsseite.

Wenn Ihr Team keine Cloud-Sitzungen verwendet, gibt es hier nichts zu konfigurieren: Sitzungen in einem Terminal oder einer IDE werden immer auf dem eigenen Rechner des Entwicklers ausgeführt. Wenn Sie Claude Code auf Ihrem eigenen Always-On-Rechner ausführen und es von anderen Geräten aus steuern möchten, verwenden Sie Remote Control, das auch auf Pro- und Max-Plänen verfügbar ist. Wenn Sie bereit sind zu beginnen, gehen Sie direkt zum Schnellstart; um die Sicherheitslage zunächst zu überprüfen, beginnen Sie mit Bereitstellung in der Produktion. Der Rest dieser Seite erklärt, wie Self-Hosting funktioniert und wann Sie es wählen sollten.

Wie selbst gehostete Umgebungen funktionieren

Self-Hosting hat drei Teile:

  • Umgebung: ein benanntes Ziel, an das Cloud-Sitzungen gesendet werden können. Ihre Organisation erstellt Umgebungen in den claude.ai Admin-Einstellungen, und jede gruppiert einen Satz von Runnern.
  • Runner: ein Programm, das auf Hosts in Ihrem Netzwerk ausgeführt wird. Runner führen die Sitzungen aus; die Idee ist die gleiche wie bei einem selbst gehosteten CI-Runner.
  • Sitzung: eine Claude Code-Aufgabe, die ein Entwickler gestartet hat.

Wenn ein Entwickler eine Cloud-Sitzung startet, zeigt die Sitzungsstart-UI eine Umgebungsauswahl an, die von Anthropic gehostete Umgebungen neben allen von Ihrer Organisation erstellten auflistet. Wenn er Ihre auswählt, platziert die Kontrollebene von Anthropic die Sitzung in der Warteschlange Ihrer Umgebung, wo ein Runner sie beansprucht, das vom Entwickler gewählte Repository klont und einen Claude Code-Prozess auf Ihrem Host startet, um ihn auszuführen. Der Runner authentifiziert sich bei Ihrem Git-Host mit Anmeldedaten, die Sie konfigurieren; Git konfigurieren behandelt die Optionen. Sitzungen erreichen Ihre internen Services von innen in Ihrem Netzwerk aus, und Ihren Git-Host auf die gleiche Weise, wenn er intern ist; der Datenverkehr zu Anthropic, das Abfragen der Warteschlange, der Ereignisstrom der Sitzung und standardmäßig die Modellableitung, ist ausgehend HTTPS zu api.anthropic.com, mit der kurzen Liste weiterer Hosts, die Sitzungen in Netzwerkanforderungen erreichen können. Anthropic verbindet sich niemals mit Ihrem Netzwerk.

Architekturdiagramm einer selbst gehosteten Umgebung: Ihre Netzwerkgrenze enthält einen Runner, zwei Claude Code-Sitzungsprozesse darin und Ihren Git-Host, mit api.anthropic.com außerhalb, das Warteschlange, Sitzungsstrom und Ableitung hält. Der Runner fragt die Warteschlange ab und erreicht den Git-Host, jeder Sitzungsprozess öffnet seine eigenen Stream-, Ableitungs- und Git-Verbindungen, und jede Verbindung ist ausgehend von Ihrem Netzwerk, ohne eingehende.

Die zwei Claude Code-Boxen im Diagramm sind Sitzungsprozesse: ein Runner führt zwei Sitzungen gleichzeitig aus, bis zu seiner konfigurierten Kapazität. Ein Runner bedient einen Besitzer auf einmal und sperrt sich auf diesen Besitzer, wenn er seine erste Sitzung beansprucht, sodass ausgecheckter Code sich niemals zwischen Besitzern vermischt; Runner-Lebenszyklus behandelt die Regel.

Sie können Runner selbst starten und am Laufen halten, oder Sie führen den Autoscaling-Orchestrator aus, einen zweiten Prozess, den Sie hosten, der Runner startet, wenn Sitzungen in der Warteschlange sind; jeder Runner beendet sich selbst, wenn seine Arbeit abgeschlossen ist. In jedem Fall richten Sie die Umgebung einmal ein, und sie wird in der Auswahl auf jeder unterstützten Oberfläche angezeigt.

Verfügbarkeit und Einschränkungen

Überprüfen Sie diese vor der Planung eines Rollouts:

Warum Self-Hosting

Die meisten Teams werden besser von von Anthropic gehosteten Umgebungen bedient, die keine Infrastruktur zum Ausführen oder Warten benötigen. Self-Hosting ist für Teams, deren Netzwerk-, Tooling- oder Compliance-Anforderungen erfordern, dass die Sitzungsausführung auf einer Infrastruktur erfolgt, die sie kontrollieren. Wenn das auf Sie zutrifft, planen Sie für die operative Verantwortung, die es mit sich bringt: Sie erstellen und warten das Runner-Image, betreiben die Flotte und kontrollieren sein Netzwerk.

Im Gegenzug bietet Self-Hosting Ihnen Netzwerkzugriff, benutzerdefinierte Tools und Compliance-Kontrolle:

  • Netzwerkzugriff: Sitzungen werden in Ihrem Netzwerk ausgeführt und können interne Services, Datenbanken und Registries erreichen, ohne sie dem öffentlichen Internet auszusetzen
  • Benutzerdefinierte Tools: Installieren Sie Compiler, SDKs und interne CLIs in Ihrem Runner-Image vor, damit jede Sitzung bereit zum Erstellen startet
  • Compliance: Repository-Checkouts und Build-Artefakte bleiben auf einer Infrastruktur, die Sie kontrollieren. Der Sitzungsinhalt wird weiterhin an api.anthropic.com gesendet.

Umgebungen, Runner und Sitzungen

Umgebungen werden auf der Seite Cloud environments in den Admin-Einstellungen von claude.ai verwaltet; Runner sind Prozesse, die Sie auf Ihrer eigenen Infrastruktur starten und verwalten.

Zentrale Begriffe

Diese Begriffe kommen auf allen Seiten zu selbst gehosteten Umgebungen vor:

Begriff Bedeutung
Umgebung Eine benannte Gruppe Ihrer Runner, die in den Einstellungen von claude.ai erstellt wird. Sitzungen werden an eine Umgebung weitergeleitet, nicht an einen einzelnen Runner.
Umgebungsgeheimnis Die einzelne gemeinsame Anmeldeinformation, mit der sich Runner authentifizieren und bei der Umgebung registrieren. Wird einmalig beim Erstellen der Umgebung angezeigt und ist in der Admin-Oberfläche als environment key bezeichnet.
Runner Der langlebige Prozess, den Sie deployen. Ein Runner registriert sich bei der Umgebung, erhält ein Runner-Token und fragt nach Sitzungen ab.
Sitzung Eine Claude Code-Aufgabe, gestartet über claude.ai, die mobile App oder eine andere Anthropic-Oberfläche wie eine geplante Aufgabe oder einen Agenten. Jede Sitzung läuft als untergeordneter Claude Code-Prozess, den der Runner startet.

In API-Feldern, Token-Claims und Metriknamen erscheint die Umgebung als pool, und die Umgebungs-ID ist die pool_id. Die Referenz ordnet die beiden Schreibweisen einander zu, einschließlich der veralteten pool-Flag-Namen.

Ein Runner bedient jeweils nur einen Eigentümer. Die erste Sitzung, die ein Runner übernimmt, bindet den Runner an den Eigentümer dieser Sitzung, und der Runner führt anschließend nur Sitzungen für diesen Eigentümer aus, bis zu einer konfigurierten Kapazität. Wer der Eigentümer ist, hängt davon ab, wie die Sitzung gestartet wurde:

  • Von einem Benutzer gestartete Sitzungen: Der Eigentümer ist das Konto dieses Benutzers.
  • Claude Tag-Channel-Sitzungen: Claude führt sie ohne zugeordnetes Benutzerkonto aus, daher ist der Eigentümer der Claude Tag-Agent, der die Sitzung gestartet hat. Jede Channel-Sitzung, die dieser Agent startet, hat denselben Eigentümer, unabhängig davon, wer die Slack-Nachricht gesendet hat. Ein an ihn gebundener Runner bedient also Sitzungen, die verschiedene Personen gestartet haben, wenn Sie ihn mit einer --capacity über eins oder mit einem positiven --drain-grace-sec ausführen.

Die minimale Flottengröße entspricht daher der Anzahl der Eigentümer, die Sie gleichzeitig aktiv erwarten, wobei Benutzer und Claude Tag-Agenten mitgezählt werden.

Lebenszyklus einer Sitzung

Wenn ein Entwickler eine Sitzung startet und Ihre Umgebung auswählt, stellt die Control Plane von Anthropic die Sitzung in die Warteschlange der Umgebung. Von dort aus:

  1. Ein Runner mit freier Kapazität beansprucht die Sitzung und hält eine Lease darauf.
  2. Der Runner klont das Repository in sein Arbeitsverzeichnis und startet einen untergeordneten Claude Code-Prozess.
  3. Der untergeordnete Prozess streamt Ereignisse über HTTPS zurück, während der Runner weiter abfragt; jede Abfrage erneuert die Lease und dient zugleich als Heartbeat.
  4. Wenn der Runner keine Abfragen mehr sendet, läuft seine Lease nach etwa 60 Sekunden ab. Der Server kann dann einige Minuten und manchmal länger benötigen, um die Sitzung für einen anderen Runner erneut in die Warteschlange zu stellen.

Der Runner gibt jeder Abfrage-Anfrage 10 Sekunden Zeit. Wenn eine Anfrage das Zeitlimit überschreitet, verloren geht oder eine Antwort erhält, die der Runner nicht parsen kann, bedient der Runner weiterhin seine laufenden Sitzungen und versucht es nach ein bis zwei Sekunden erneut, statt auf die nächste planmäßige Abfrage zu warten. Beispielsweise erzeugt ein abfangender Proxy, der die Abfrage mit einer eigenen Seite beantwortet, eine Antwort, die der Runner nicht parsen kann. Jedes Mal, wenn eine weitere Anfrage auf eine dieser Arten fehlschlägt, verdoppelt der Runner den Abstand bis zum nächsten Wiederholungsversuch, bis zu 20 Sekunden, und verkürzt den Abstand, sobald die Lease kurz vor dem Ablauf steht.

Lebenszyklus eines Runners

Die erste Sitzung, die ein Runner übernimmt, bindet den Runner an den Eigentümer dieser Sitzung, und der Runner führt bis zu --capacity gleichzeitige Sitzungen für diesen Eigentümer aus. Solange der Runner aktive Sitzungen hat, weder ein Shutdown-Signal erhalten noch seinen Retire-Zeitpunkt erreicht hat, beansprucht er weiterhin Arbeit aus der Warteschlange des gebundenen Eigentümers. Was nach dem Ende dieser Sitzungen geschieht, hängt von --drain-grace-sec ab:

  • Beim Standardwert 0: Der Runner beendet sich, sobald seine aktiven Sitzungen abgeschlossen sind, ohne nach weiteren abzufragen, sodass der Orchestrator, unter dem Sie ihn deployen, etwa Kubernetes, ihn mit einem frischen Datenträger neu starten kann, bereit für jeden beliebigen Eigentümer.
  • Bei einem positiven Wert: Der Runner fragt die Warteschlange des gebundenen Eigentümers noch so viele Sekunden lang ab, bevor er sich beendet.

Dieser Lebenszyklus isoliert den ausgecheckten Code jedes Eigentümers, ohne dass der Runner den Zustand auf dem Datenträger zwischen Eigentümern löschen muss.

Wie Ihre Infrastruktur einen Runner stoppt, entscheidet darüber, ob Sie --retire-at benötigen. Ein Beenden, das SIGTERM sendet, erfordert kein Flag: Der Runner leert sich wie unter Zeitpunkt des Herunterfahrens beschrieben oder bedient die bereits gehaltenen Sitzungen weiter, wenn Sie --defer-shutdown-max-min setzen. Wenn Ihre Infrastruktur Hosts stattdessen zu einem bekannten Uhrzeitpunkt ohne Signal zerstört oder mit einer Schonfrist, die zum Leeren zu kurz ist, etwa bei einer Begrenzung der Sandbox-Lebensdauer oder der Rückforderung von Spot-Instanzen, übergeben Sie --retire-at <epoch-seconds> mit einem Wert einige Minuten vor diesem Zeitpunkt. Zum Retire-Zeitpunkt:

  1. Der Runner nimmt keine neue Arbeit mehr an.
  2. Der Runner gibt jede aktive Sitzung über denselben Freigabepfad frei, den das Flag --release-idle-session-min verwendet, sodass die Sitzung auf einem frischen Runner fortgesetzt wird, wenn der Benutzer seine nächste Nachricht sendet. Wann der Runner jede Sitzung freigibt, hängt von ihrem Zustand ab:
    • Eine Sitzung, die sich mitten in einem Turn befindet, gibt der Runner nach Abschluss dieses Turns frei. Zuvor wartet er darauf, dass der Prozess der Sitzung das Ende des Turns an Anthropic meldet, höchstens jedoch SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS lang. Vor v2.1.280 gab der Runner die Sitzung frei, sobald der Turn abgeschlossen war.
    • Wenn ein Turn endet und Hintergrundaufgaben weiterlaufen lässt, wartet der Runner bis zu 60 Sekunden auf sie und gibt die Sitzung dann frei, auch wenn sie noch laufen. Wenn die Aufgaben abgeschlossen sind, der nachfolgende Turn, der ihre Ergebnisse liest, aber noch nicht gelaufen ist, behält der Runner die Sitzung, bis dieser Turn abgeschlossen ist, und wartet höchstens SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS lang darauf, dass dieser Turn beginnt.
  3. Der Runner beendet sich mit Exit-Code 0, sobald alle seine Sitzungen freigegeben sind.

Ein Turn, der zum Zeitpunkt des Beendens noch läuft, geht trotzdem verloren; Zeitpunkt des Herunterfahrens erläutert, wie Sie den Puffer bemessen. Ohne --retire-at ist ein signalloses Beenden des Hosts nicht von einem Absturz zu unterscheiden: Die Control Plane verzeichnet einen verlorenen Worker statt einer sauberen Freigabe, und die Sitzung wird erneut für einen anderen Runner in die Warteschlange gestellt.

Netzwerkpfade

Der Runner und seine Sitzungen bauen mehrere Arten ausgehender Verbindungen auf, und es ist keine eingehende Konnektivität von Anthropic erforderlich:

  • Control Plane: Der Runner fragt api.anthropic.com nach Arbeit ab und sendet Ereignisse zum Einrichtungsfortschritt und zu Fehlern, alles über ausgehendes HTTPS. Die Abfragen dienen zugleich als Heartbeat des Runners.
  • Git: Der Runner klont von Ihrem Git-Host und pusht dorthin, über HTTPS oder SSH, authentifiziert mit Anmeldedaten, die Ihr Deployment bereitstellt. Unter Git konfigurieren finden Sie die Optionen, einschließlich pro Sitzung erzeugter Anmeldedaten. Mit dem Anthropic-Git-Proxy läuft der Git-Datenverkehr für Repositorys auf github.com stattdessen über api.anthropic.com.
  • Untergeordneter Sitzungsprozess: Der untergeordnete Claude Code-Prozess hält den Ereignisstream der Sitzung zu api.anthropic.com und führt eigene ausgehende Aufrufe für die Modellinferenz und für Git-Befehle aus, die während der Sitzung ausgeführt werden. In einer Sitzung, die von Anthropic verwaltetes Git verwendet, sendet der untergeordnete Prozess seinen git- und gh-Datenverkehr für github.com über eine WebSocket-Verbindung, die er zu api.anthropic.com öffnet.
  • SCM-Konnektor: Der optionale SCM-Konnektor des Orchestrators ist nicht verfügbar, daher wird sein Tunnel nicht geöffnet. Der Tunnel ist eine WebSocket-Verbindung zu api.anthropic.com.

Die vollständige Liste der ausgehenden Ziele finden Sie unter Netzwerkanforderungen. Das Diagramm oben zeigt diese Pfade, mit Ausnahme des optionalen SCM-Konnektors und der Verbindung für von Anthropic verwaltetes Git.

Standardmäßig verwendet die Modellinferenz die Anthropic API. Die Control Plane übermittelt jeder Sitzung den API-Endpunkt, und die Sitzung authentifiziert sich mit einem von Anthropic ausgestellten, auf die Sitzung beschränkten OAuth-Token. Wie Sie Modellanfragen stattdessen an Ihr eigenes Cloud-Konto senden, erfahren Sie unter Modellanfragen an Bedrock oder Agent Platform senden.

Unternehmens-Egress-Proxys werden unterstützt. Der Runner und der optionale Autoscaling-Orchestrator berücksichtigen die unter Netzwerkkonfiguration beschriebenen Proxy- und mTLS-Umgebungsvariablen, etwa HTTPS_PROXY und NO_PROXY; setzen Sie sie in der Umgebung jedes Prozesses. Die Variablen gelten für Aufrufe an die Control Plane, für den WebSocket des SCM-Konnektors des Orchestrators und für den integrierten Klonvorgang bei HTTPS-Remotes, und Sitzungen erben sie vom Runner. Das Streaming von Sitzungen verwendet Server-Sent Events über HTTPS, daher darf ein Proxy im Pfad Antworten nicht puffern.

Wenn Ihr Proxy zusätzlich einen Proxy-Authorization-Header erfordert, kann der Runner ihn jeder Verbindung hinzufügen, die er zum Proxy öffnet; siehe Bei einem Egress-Proxy authentifizieren.

Was auf Ihrer Infrastruktur bleibt

Repository-Checkouts, Build-Artefakte, Geheimnisse und alle Dateien, die eine Sitzung erstellt oder ändert, bleiben auf den Maschinen, die Sie bereitstellen. Die Konversation selbst, einschließlich Prompts, Antworten und Tool-Ergebnissen, geht an api.anthropic.com, und Anthropic speichert das Sitzungstranskript, damit Sie die Sitzung von einer anderen unterstützten Oberfläche aus fortsetzen können. Wenn ein Runner Modellanfragen an Amazon Bedrock oder die Agent Platform von Google Cloud sendet, geht die Konversation weiterhin im Event-Stream der Sitzung an api.anthropic.com.

Eine selbst gehostete Umgebung verschiebt die Sitzungsausführung in Ihr Netzwerk. Die Kontrolleben bleibt von Anthropic gehostet: Sitzungsorchestration, Queueing und die claude.ai Schnittstelle werden weiterhin auf der Infrastruktur von Anthropic ausgeführt.

Erste Schritte

Die Self-Hosting-Umgebungsseiten sind nach dem organisiert, was Sie tun:

  • Schnellstart: Installieren Sie Claude Code, erstellen Sie eine Umgebung, starten Sie einen Runner und leiten Sie Ihre erste Sitzung weiter
  • Bereitstellung in der Produktion: Sicherheitshärtung, Netzwerk-Egress, Git-Anmeldedaten, Kubernetes- und Compose-Rezepte, bekannte Probleme und Fehlerbehebung
  • Sitzungen anpassen: Wrapper-Skripte für pro-Sitzung Anmeldedaten, Lifecycle-Hooks, On-Demand-Runner, MCP-Server und Berechtigungen
  • End-to-End testen: Ein CI-Smoke-Test, der ein Runner-Image überprüft, bevor Sie es hochstufen
  • Referenz: Jedes CLI-Flag, jede Umgebungsvariable, jede Metrik und der Health-Endpunkt
  • Sitzungsidentität überprüfen: Validieren Sie das Sitzungs-Token von Ihren eigenen Services, bevor Sie Zugriff gewähren