Skip to main content
Selbstgehostete Umgebungen befinden sich in der öffentlichen Beta auf Team- und Enterprise-Plänen; ein Inhaber aktiviert sie, indem er Selbstgehostete Umgebungen zulassen auf der Cloud-Umgebungen Admin-Seite einschaltet. Diese Seite ist die Flag- und Metrik-Referenz; siehe den Schnellstart für die Einrichtung und In Produktion bereitstellen für die Fleet-Rezepte.
Diese Seite ist die Referenz für die zwei Prozesse, die Sie in einer selbstgehosteten Umgebung ausführen: der Runner, der Claude Code Cloud-Sitzungen auf Ihren Hosts ausführt, und der optionale Autoscaling-Orchestrator, der Runner startet, wenn Sitzungen in die Warteschlange eingereiht werden. Jeder hat seine eigene Flag-Tabelle. Beide laufen auf Linux- oder macOS-Hosts, wobei die Standardwerte wie /workspace und ~/.claude angenommen werden. Führen Sie claude self-hosted-runner --help aus, um die autoritative Liste in Ihrer installierten Version zu erhalten. Metrische Reihen und einige wenige API-Felder verwenden immer noch pool für das, was diese Seiten eine Umgebung nennen; beide Begriffe bezeichnen dasselbe. Die Umgebungs-ID ist das Feld pool_id mit der Form ccpool_...: Überall dort, wo diese Seiten einen pool-Bezeichner anzeigen, benennt er die Umgebung. CLI-Flags und Umgebungsvariablen schreiben es als environment, wie z. B. --environment-secret-file; die veralteten pool-Schreibweisen funktionieren immer noch, wie die Zeile --environment-secret-file beschreibt.

​
Runner-CLI-Flags

Die meisten Flags haben eine entsprechende Umgebungsvariable. Wenn beide gesetzt sind, hat das Flag Vorrang. Duration-Flags nehmen Minuten oder Sekunden in der CLI, aber die gepaarte Umgebungsvariable ist immer in Millisekunden, angezeigt durch das Suffix _MS, und die Spalte Standard zeigt die Einheit des Flags: --exit-if-unused-min 10 entspricht SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, und ein Helm-Wert wie SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" bedeutet 15 Millisekunden, nicht die 15-Minuten-Standard. Die meisten Duration-Flags haben ein Maximum, das gewählt wurde, um jeden Timeout unter der 32-Bit-Timer-Obergrenze der Laufzeit von ungefähr 24,85 Tagen zu halten. Die --*-min Flags sind auf 10080 Minuten, 7 Tage begrenzt; --drain-grace-sec auf 604800 Sekunden, auch 7 Tage; und --drain-wait-sec auf 86400 Sekunden, 24 Stunden. --session-stop-grace-sec und --post-session-hook-timeout-sec sind unbegrenzt. Das Überschreiten einer Obergrenze verhält sich je nach Oberfläche unterschiedlich:
  • Flag: Der Start schlägt mit einem Fehler fehl.
  • Umgebungsvariable: Der Runner begrenzt den Wert auf die Timer-Obergrenze, anstatt ihn abzulehnen.

​
Orchestrator-CLI-Flags

Der Unterbefehl self-hosted-runner orchestrator, der On-Demand-Runner erzeugt, akzeptiert --api-url, --environment-secret-file, --hooks-dir, --health-port und --log-level mit denselben Standardwerten wie der Runner und, wo das Flag des Runners einen hat, dieselbe Umgebungsvariable, außer dass --hooks-dir erforderlich ist und einen spawn-runner Hook enthalten muss. Es nimmt auch seine eigenen Flags:

​
SCM-Connector-Flags

Der Orchestrator kann eine stehende WebSocket-Verbindung zur Anthropic-Kontrolleben halten, sodass gehostete Pre-Session-Flows, wie der Repository-Picker und der Branch- oder Ref-Resolver, einen GitHub Enterprise Server-Host erreichen können, der nur von innerhalb Ihres Netzwerks erreichbar ist. Der Connector bleibt aus, es sei denn, Sie setzen --scm-connector-host. Der Connector authentifiziert sich mit dem bestehenden Umgebungsgeheimnis des Orchestrators und verbindet sich automatisch erneut: mit exponentiellem Backoff bei einer unterbrochenen Verbindung oder einer festen 30-Sekunden-Verzögerung, wenn die Kontrolleben die Verbindung schließt, weil ein anderes Orchestrator-Replikat sie bereits hält.

​
Nur-Umgebungsvariablen-Einstellungen

Diese Runner-Einstellungen werden nur aus der Umgebung gelesen und decken Verhalten ab, das die meisten Bereitstellungen bei der Standardeinstellung belassen:

​
Telemetrie

Session-Kinder senden operative Telemetrie an Anthropic, es sei denn, Sie schalten sie aus. Kein Code oder Repository-Inhalt wird gesendet. Setzen Sie Telemetrie-Variablen auf dem Runner-Prozess; der Runner bekräftigt sie erneut, nachdem er von der Kontrolleben bereitgestellte Umgebungsvariablen angewendet hat, sodass die Einstellung des Operators immer Vorrang hat. Ein Steuerelement ist spezifisch für selbstgehostete Umgebungen: CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 meldet sich für Datadog-Operationsmetriken an, die in selbstgehosteten Umgebungen standardmäßig aus sind. Die allgemeinen Claude Code-Telemetrie-Steuerelemente, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING und CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, gelten für Session-Kinder wie in der Umgebungsvariablen-Referenz dokumentiert. DISABLE_GROWTHBOOK ist verwandt, aber anders: Das Setzen von DISABLE_GROWTHBOOK=1 deaktiviert das Abrufen von Feature-Flags, und die Telemetrie bleibt an, es sei denn, DISABLE_TELEMETRY ist auch gesetzt. CLAUDE_CODE_ENABLE_TELEMETRY ist nicht verwandt: Es aktiviert OpenTelemetry-Export zu Ihrem eigenen Collector, wie in Überwachung beschrieben, und steuert nicht Anthropics Analytik.

​
Health-Endpunkt

Der Runner bedient GET /healthz auf dem konfigurierten Health-Port. Die Antwort ist 200 OK, wann immer der Prozess am Leben ist, unabhängig davon, in welchem Zustand sich die Abfrageschleife befindet, sodass ein HTTP-Probe auf diesem Endpunkt nur einen toten Prozess erkennt. Der JSON-Body beschreibt den aktuellen Zustand:
Verwenden Sie last_poll_age_ms als Lebendigkeitssignal in benutzerdefinierten Proben; ein Wert, der unbegrenzt wächst, zeigt an, dass die Abfrageschleife steckt. Sowohl last_poll_at als auch last_poll_age_ms sind null, bis die erste Abfrage abgeschlossen ist. Der Orchestrator bedient sein eigenes /healthz auf seinem Health-Port. Sein Endpunkt gibt immer 200 zurück, und der Body trägt ein Feld connected, das meldet, ob die letzte Abfrage erfolgreich war, plus Pro-Status-Spawn-Queue-Zählungen in queue_counts. Gate-Bereitschaft und Warnungen auf connected statt auf dem Statuscode. Wenn der SCM-Connector konfiguriert ist, trägt der Body des /healthz des Orchestrators auch scm_connector_connected und ein Objekt scm_connector mit connected, last_connected_at, last_error, reconnects und requests_forwarded. Beide Felder sind null, wenn --scm-connector-host nicht gesetzt ist.

​
Prometheus-Metriken

Jeder Runner bedient Prometheus-Metriken bei GET /metrics auf demselben Port wie /healthz. Wichtige Reihen: Der Orchestrator bedient seine eigenen Reihen bei GET /metrics auf demselben Port wie sein /healthz: Für Autoscaling wählen Sie die Reihe, die zu Ihrem Skalierungsstil passt, und gaten Sie sie, bevor sie den Scaler speist:
  • Queue-Tiefe-Skalierung: Speisen Sie claude_code_self_hosted_orchestrator_pool_pending_sessions in Ihren HPA- oder KEDA-Scaler, nicht queue_pending_sessions.
  • Kapazitäts-Skalierung: Skalieren Sie auf das Verhältnis der active_sessions des Runners zu capacity.
  • Gate auf connected: Filtern Sie die Abfrage mit claude_code_self_hosted_orchestrator_connected == 1 pro Instanz, sodass der veraltete Wert eines getrennten Replikas nicht den Scaler speist.
Während eines vollständigen Abfrageausfalls, jedes Replikat getrennt, gibt die gated-Abfrage keine Daten zurück. HPA hält die aktuelle Replikaanzahl bei einer fehlenden Metrik, aber KADAs Prometheus-Scaler bei seinem Standard ignoreNullValues: "true" liest das leere Ergebnis als Null und skaliert ein; setzen Sie ignoreNullValues: "false" auf dem ScaledObject, optional mit einem fallback Replikafloor. Der folgende Prometheus Operator PodMonitor deckt beide Prozesse ab. Er wählt Pods nach dem Label app.kubernetes.io/part-of: claude-code-self-hosted-runner und dem benannten Port health, den das Kubernetes-Rezept setzt; passen Sie die Namespaces an Ihre Bereitstellung an:
Diese Beispiel-Warnregeln sind ein Ausgangspunkt; stimmen Sie die Schwellwerte für Ihre Fleet-Größe ab:

​
Durchlauf-Session-Kind-Metriken

Jede Sitzung läuft in ihrem eigenen Kind-Prozess mit ihren eigenen OpenTelemetry-Metriken; bei --capacity über eins schreibt der Runner um, wie diese Kind-Metriken verfügbar gemacht werden. Das Setzen von OTEL_METRICS_EXPORTER=prometheus auf dem Runner-Host und CLAUDE_CODE_ENABLE_TELEMETRY=1 in der Umgebung der Sitzung, zum Beispiel aus Ihrem Wrapper-Skript oder der Umgebung des Runners selbst, die Sitzungen erben, macht die Zähler- und Gauge-Instrumente jedes Kindes auf dem /metrics Endpunkt des Runners erneut verfügbar, neben den Reihen des Runners. Der Runner schreibt den Exporter des Kindes um, um über OTLP zu einem Loopback-only-Receiver auf dem Health-Port zu pushen, markiert jede Reihe mit session_id- und client_platform-Labels und entfernt die Reihen einer Sitzung, wenn diese Sitzung endet. Histogramme gehen nicht durch, und eine Kind-Metrik, deren Name mit dem eigenen Präfix des Runners kollidieren würde, wird gelöscht. Bei der Standard --capacity 1 gilt die Umschreibung nicht: Das Kind des Kindes bindet seinen eigenen Prometheus-Endpunkt auf Port 9464 wie üblich.

​
Session-Lebenszyklus-Zähler-Semantik

Die Zähler sessions_started_total, sessions_completed_total, sessions_failed_total und sessions_interrupted_total klassifizieren jede Sitzung danach, wie sie endete. Jedes erzeugte Session-Kind erhöht sessions_started_total zum Spawn-Zeitpunkt, und genau einer der anderen drei erhöht sich beim Beenden, sodass sessions_started_total minus die Summe der anderen drei der Anzahl der derzeit laufenden Session-Kinder entspricht.
  • completed: Die Sitzung endete sauber. Dies deckt das Kind ab, das auf eigene Faust mit Code 0 beendet wird, die Sitzung wird archiviert oder gelöscht, während das Kind noch verbunden war, und der Runner gibt den Slot sauber zurück: Freigabe der Sitzung beim Idle-Timeout, zur Retire-Zeit oder am --kill-session-after-min Limit; ein Startup-Timeout; oder ein serverseitiges Deassign, das die Abfrageschleife bemerkte, bevor das Kind beendet wurde. Erhöht sessions_completed_total.
  • failed: Das Kind beendete sich auf eigene Faust mit einem Nicht-Null-Code, entweder ein Crash oder ein Setup-Fehler nach dem Erzeugen. Erhöht sessions_failed_total.
  • interrupted: Der Runner beendete das Kind aus operativen Gründen, die weder ein Session-Erfolg noch ein Runner-Fehler sind, wie eine Entleerung oder die Beendigung einer Sitzung, die sich noch auf dem Runner befand, wenn das SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS Kulanzfenster nach seinem --kill-session-after-min Limit endete. Ein Kubernetes-Rolling-Restart, der SIGTERM sendet, ist ein Beispiel für eine Entleerung. Erhöht sessions_interrupted_total.
Vor v2.1.260 beendete der Runner jede Sitzung, die ihr --kill-session-after-min Limit erreichte, und zählte sie in sessions_interrupted_total. Der post-session Hook CLAUDE_RUNNER_EXIT_REASON klassifiziert saubere Übergaben unterschiedlich. Der Hook meldet eine Freigabe, ein Startup-Timeout und eine Server-Deassign als interrupted, da der Runner das Kind stoppte. Diese Zähler zeichnen die gleichen Ereignisse als completed auf, da der Slot sauber zurückgegeben wurde. Wenn Sie Hook-Quittungen direkt gegen sessions_completed_total abstimmen, unterzählen Sie Abschlüsse. Verwenden Sie den Hook für Pro-Session-Garantien und die Zähler für Aggregatraten. In einer One-Shot-Umgebung, --capacity 1 mit dem Standard --drain-grace-sec 0, beendet sich jeder Runner-Prozess Momente nach seiner einen Sitzung endet. sessions_completed_total, sessions_failed_total und sessions_interrupted_total erhöhen sich nur beim Session-Ende, direkt bevor dieser Ausstieg, sodass ein Prometheus-Scrape alle 15 bis 60 Sekunden die Erhöhung selten erfasst, bevor die Reihen des Runners verschwinden; diese drei End-of-Session-Zähler sind die Terminal-Zähler, auf die sich der Rest dieses Abschnitts bezieht. sessions_started_total erhöht sich beim Erzeugen und bleibt für die Lebensdauer der Sitzung sichtbar, sodass es zuverlässig angezeigt wird, aber in einer One-Shot-Umgebung liest es näher an “Sitzungen, die derzeit laufen” als an einer kumulativen Anzahl. Verwenden Sie die Reihe in dieser Tabelle für das entsprechende Ziel statt der Terminal-Zähler: Die orchestrator_* Zeilen existieren nur auf Umgebungen, die den On-Demand-Orchestrator ausführen. In einer festen Fleet, deren Runner ihre Sitzungen mit --drain-grace-sec über 0 überleben, verwenden Sie sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) für Durchsatz; in einer One-Shot-Fleet hat diese Reihe das gleiche Scrape-Fenster-Problem wie die Terminal-Zähler, also verlassen Sie sich stattdessen auf die Zählung der Sitzungen in der Warteschlange. Überprüfen Sie den Rückstand auf der Registerkarte Aktivität der Umgebung, auf der Cloud-Umgebungen-Administratorseite: Die Runner exportieren keine Queue-Tiefe-Reihe. Für Pro-Session-Ergebnis-Berichterstattung verwenden Sie stattdessen den post-session Hook: Er wird bei jedem Session-Ende ausgelöst, wo ein Kind-Prozess erzeugt wurde, abgesehen von abruptem Runner-Beendigung wie eine VM-Preemption, pro dem eigenen Vertrag des Hooks.

​
Nächste Schritte