Referenz für selbstgehostete Umgebungen

Vollständige Referenz für den selbstgehosteten Runner und Orchestrator: CLI-Flags, Umgebungsvariablen und Prometheus-Metriken.

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:

{
  "status": "ok",
  "runner_id": "ccrunner_...",
  "active_sessions": 2,
  "last_poll_at": "2026-03-31T18:04:11.220Z",
  "last_poll_age_ms": 842
}

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:

# Beispiel Prometheus Operator PodMonitor für den Claude Code Self-Hosted
# Runner + Orchestrator. Passen Sie die Namespace- und Label-Selektoren an Ihre
# Bereitstellung an. Sowohl der Runner als auch der Orchestrator bedienen /metrics auf
# ihrem --health-port (Standard 8080).
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-code-self-hosted-runner
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - claude-runners
  selector:
    matchExpressions:
      # Passt die Runner-Bereitstellung aus dem Kubernetes-Rezept sowie alle
      # On-Demand-Runner-Jobs und Orchestrator-Pods an, die Sie gleich beschriften
      # und einen benannten 'health' containerPort geben.
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

Diese Beispiel-Warnregeln sind ein Ausgangspunkt; stimmen Sie die Schwellwerte für Ihre Fleet-Größe ab:

# Beispiel Prometheus-Warnregeln für den Claude Code Self-Hosted Runner
# + Orchestrator. Stimmen Sie die Schwellwerte für Ihre Fleet-Größe und SLOs ab.
groups:
  - name: claude-code-self-hosted-runner
    rules:
      - alert: ClaudeRunnerPollStale
        expr: claude_code_self_hosted_runner_last_poll_age_seconds > 60
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }} hat nicht in >60s abgefragt"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "Runner führen gemischte Versionen aus"
      - alert: ClaudeRunnerInitErrorsHigh
        expr: increase(claude_code_self_hosted_runner_session_init_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: >3 Session-Init-Fehler in 10m (Checkout-Hook / Git / Token / Pre-Init-Kind-Crash)"
      - alert: ClaudeRunnerPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: PollWork fehlgeschlagen ({{ $value | humanize }}/s über 5m)"
      - alert: ClaudeRunnerSessionStartHookErrors
        expr: increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: >3 SessionStart-Hook-Fehler in 10m"

  - name: claude-code-self-hosted-orchestrator
    rules:
      - alert: ClaudeOrchestratorDisconnected
        expr: claude_code_self_hosted_orchestrator_connected == 0
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} kann die Anthropic-Kontrolleben nicht erreichen"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} hat nicht in >90s abgefragt (Abfrageschleife wartet auf Hook-Ausführung)"
      - alert: ClaudeOrchestratorCircuitBroken
        expr: claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions > 0
        for: 1m
        labels: {severity: critical}
        annotations:
          summary: "{{ $value }} Sitzungen unterbrochen — spawn-runner Hook ist wiederholt nicht wiederholbar; beheben Sie die Infrastruktur und versuchen Sie es erneut von der Registerkarte Aktivität"
      - alert: ClaudeOrchestratorPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }}: PollSpawnHints fehlgeschlagen ({{ $value | humanize }}/s über 5m)"
      - alert: ClaudeOrchestratorSpawnHookFailing
        expr: sum by (pod) (increase(claude_code_self_hosted_orchestrator_spawn_hooks_total{result!="ok"}[5m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }}: >3 spawn-runner Hook-Fehler in 5m"

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

• Selbstgehostete Umgebungen: die Umgebung, den Runner und das Session-Modell; der Schnellstart und In die Produktion bereitstellen enthalten Einrichtung und Betrieb
• Passen Sie Sitzungen an: Wrapper-Skripte, Lifecycle-Hooks und On-Demand-Runner
• Überprüfen Sie die Session-Identität: das Session-Token, seine Ansprüche und wie man es überprüft