Self-hosted environments reference

This is the lookup page for the two processes you operate in a self-hosted environment: the runner, which executes cloud sessions on your hosts, and the optional orchestrator, which starts runners on demand. Both run on Linux or macOS, which is what defaults such as /workspace and ~/.claude assume. For the version you actually have installed, claude self-hosted-runner --help is the final word.

Naming: environment versus pool

Metric names and some API fields say pool where these pages say environment. They are the same thing. The environment ID is the pool_id field and looks like ccpool_.... Flags and environment variables use environment (for example --environment-secret-file), and the older pool spellings still work with a deprecation notice.

How flags and variables relate

• Most flags have an environment variable twin. If both are set, the flag wins.
• Duration variables are always in milliseconds, marked by an _MS suffix, even when the flag takes minutes or seconds. --exit-if-unused-min 10 equals SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000. A Helm value of SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" means 15 milliseconds, not 15 minutes. This one has bitten me.
• Duration caps keep timers under the runtime's 32-bit ceiling (about 24.85 days): every --*-min flag caps at 10080 minutes (7 days), --drain-grace-sec at 604800 seconds (7 days), and --drain-wait-sec at 86400 seconds (24 hours). --session-stop-grace-sec and --post-session-hook-timeout-sec have no cap. Exceed a cap on a flag and startup fails; exceed it in a variable and the value is clamped to the ceiling.

Runner flags

I have grouped the runner's flags by job. Every flag here belongs to claude self-hosted-runner.

Identity and registration

Workspace and sessions

Timeouts and session lifetime

Shutdown and retirement

Git

Network, health and logging

A worked example

A typical production line for a single-session, git-proxy runner on Kubernetes:

claude self-hosted-runner \
  --environment-secret-file /etc/claude/environment-secret \
  --capacity 1 \
  --use-anthropic-git-proxy \
  --configure-git \
  --confine-repo-settings enforce \
  --release-idle-session-min 30 \
  --kill-session-after-min 480 \
  --remove-session-state \
  --log-file /var/log/claude-runner.log

Orchestrator flags

claude self-hosted-runner orchestrator launches on-demand runners. It shares --api-url, --environment-secret-file, --hooks-dir, --health-port and --log-level with the runner (same defaults and, where the runner has one, the same variable), except that --hooks-dir is mandatory and must contain a spawn-runner hook. It does not accept the proxy-authorization flags. Its own flags:

SCM connector flags

The SCM connector is not available yet, so leave these unset. If --scm-connector-host is set, the connection never opens and the orchestrator keeps retrying, though runners still start normally.

It is designed as a standing WebSocket from the orchestrator to Anthropic so that hosted pre-session flows (repository picker, branch and ref resolution) can reach a GitHub Enterprise Server that is only routable inside your network. See GitHub Enterprise Server.

Each attempt authenticates with the environment secret and retries with exponential backoff capped at 30 seconds plus jitter.

Variables with no flag

Telemetry controls

Session children send operational telemetry to Anthropic by default; it never contains code or repository content. Set controls on the runner process, which reapplies them after server-provided variables so yours always win.

Health endpoints

Runner

GET /healthz on the health port returns 200 OK while the process is alive, regardless of the poll loop. The body tells you more:

{
  "status": "ok",
  "runner_id": "ccrunner_01HZX...",
  "active_sessions": 1,
  "last_poll_at": "2026-10-08T09:12:44.501Z",
  "last_poll_age_ms": 1310
}

last_poll_at and last_poll_age_ms are null until the first poll finishes. A last_poll_age_ms that keeps climbing means the poll loop is stuck, so use it in custom probes. A quick check from the host:

curl -s localhost:8080/healthz | jq '.last_poll_age_ms < 60000'

Orchestrator

The orchestrator's /healthz always returns 200. Gate readiness and alerts on the body's connected field (whether the last poll succeeded), and read per-state spawn queue counts from queue_counts. When the SCM connector is configured the body also has scm_connector_connected and an scm_connector object (connected, last_connected_at, last_error, reconnects, requests_forwarded); both are null otherwise.

Prometheus metrics

Both processes serve GET /metrics on their health port.

Runner series

Orchestrator series

Autoscaling signals

• Scale on queue depth with claude_code_self_hosted_orchestrator_pool_pending_sessions, not queue_pending_sessions.
• Scale on utilisation with the runner's active_sessions divided by capacity.
• Gate on claude_code_self_hosted_orchestrator_connected == 1 per instance so a disconnected replica's stale number does not drive the scaler.

During a total poll outage the gated query returns nothing. The Kubernetes HPA holds replicas on missing data, but KEDA's Prometheus scaler with its default ignoreNullValues: "true" treats empty as zero and scales in. Set ignoreNullValues: "false" on the ScaledObject, optionally with a fallback floor.

A KEDA trigger that follows that advice:

triggers:
  - type: prometheus
    metadata:
      serverAddress: http://prometheus.monitoring:9090
      query: |
        max(claude_code_self_hosted_orchestrator_pool_pending_sessions
          and on(pod) claude_code_self_hosted_orchestrator_connected == 1)
      threshold: "1"
      ignoreNullValues: "false"

Scraping and alerting

If you use the Prometheus Operator, label runner and orchestrator pods with app.kubernetes.io/part-of: claude-code-self-hosted-runner and name the port health (as the Kubernetes recipe does), then one PodMonitor covers both:

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-runners
  namespace: monitoring
spec:
  namespaceSelector: { matchNames: [claude-runners] }
  selector:
    matchLabels: { app.kubernetes.io/part-of: claude-code-self-hosted-runner }
  podMetricsEndpoints:
    - { port: health, path: /metrics, interval: 30s }

The alerts I would start with, thresholds to taste:

Passing through session metrics

Each session child has its own OpenTelemetry metrics. With OTEL_METRICS_EXPORTER=prometheus on the runner host and CLAUDE_CODE_ENABLE_TELEMETRY=1 in the session environment (from the wrapper or inherited from the runner), and --capacity above one, the runner re-exposes each child's counters and gauges on its own /metrics. It does this by pointing the child's exporter at a loopback-only OTLP receiver on the health port, adding session_id and client_platform labels, and dropping a session's series when it ends. Histograms are not passed through, and any child metric that would clash with the runner's own prefix is dropped. At --capacity 1 none of this happens; the child binds its own Prometheus endpoint on port 9464.

How the session counters classify endings

Every spawned child increments sessions_started_total at spawn and exactly one of the other three at exit, so started minus the other three equals children running now.

Before v2.1.260 every session hitting --kill-session-after-min was terminated and counted as interrupted.

The post-session hook's CLAUDE_RUNNER_EXIT_REASON reports releases, startup timeouts and server deassigns as interrupted, whereas these counters call them completed. Reconciling hook receipts against sessions_completed_total therefore undercounts completions. Use the hook for per-session guarantees and the counters for rates.

One-shot fleets. At --capacity 1 with --drain-grace-sec 0, a runner exits moments after its only session ends. The three terminal counters only tick at that moment, so a 15 to 60 second scrape rarely sees them before the series disappears. sessions_started_total is visible for the session's life, but on such a fleet it behaves more like "sessions running now". Use these instead:

The orchestrator series only exist when you run the orchestrator. On a fixed fleet whose runners outlive sessions (--drain-grace-sec above 0), sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) works for throughput. Runners export no queue depth, so check backlog in the environment's Activity tab on the Cloud environments admin page. For per-session outcomes, rely on the post-session hook, which fires on every end where a child was spawned except abrupt host loss.

Related

• Self-hosted environments
• Deploy self-hosted environments to production
• Customise self-hosted sessions
• Verify session identity
• Monitoring usage