Detailed Analysis
Anthropic's documentation for self-hosted environments in Claude Code lays out the technical reference for organizations running Claude Code's cloud sessions on their own infrastructure rather than relying entirely on Anthropic-managed compute. The system centers on two processes: a runner, which executes individual Claude Code sessions on customer-controlled Linux or macOS hosts, and an optional autoscaling orchestrator, which spins up runners on demand as sessions queue. This architecture reflects a hybrid deployment model where Anthropic retains control-plane functions—session coordination, authentication, and feature delivery—while enterprises keep sensitive code and repository content within their own network perimeter, a design that has become increasingly common among AI coding tools targeting regulated industries and security-conscious enterprises.
The documentation reveals a system built with considerable operational maturity, addressing details that only emerge from real production deployments: duration flags capped near a 32-bit timer ceiling of roughly 24.85 days, distinct behaviors for CLI flags versus environment variables when values exceed those caps (hard failure versus silent clamping), and unit inconsistencies between CLI flags (minutes/seconds) and their paired environment variables (milliseconds) that could easily trip up operators writing Helm charts or Kubernetes manifests. The explicit warning about a value like `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15"` silently meaning 15 milliseconds instead of the intended 15 minutes signals that this is a known footgun Anthropic has seen in the wild, suggesting the self-hosted runner has already accumulated meaningful enterprise adoption and support history.
A notable architectural feature is the SCM connector, which maintains a standing WebSocket connection from the orchestrator to Anthropic's control plane specifically to let hosted pre-session flows—like repository pickers and branch resolution—reach GitHub Enterprise Server instances that are only routable inside a customer's private network. This is a pragmatic solution to a common enterprise problem: cloud-hosted AI services need to interact with internal developer tooling that was never meant to be internet-facing. The reconnection logic, including exponential backoff and a fixed 30-second delay when another orchestrator replica holds the connection, indicates the system is designed for high-availability, multi-replica deployments rather than single-instance setups, further reinforcing that this is aimed at serious enterprise scale rather than hobbyist use.
The telemetry and observability sections underscore Anthropic's approach to balancing operational visibility with customer data privacy. Session children send operational telemetry by default (explicitly excluding code or repository content), but operators retain override authority since the runner re-asserts local telemetry settings after applying server-provided environment variables—an important trust signal for enterprises wary of ceding control over data flows. The layered telemetry controls (DISABLE_TELEMETRY, DO_NOT_TRACK, the self-hosted-specific Datadog opt-in, and the unrelated OpenTelemetry export mechanism) show a system accommodating multiple, sometimes overlapping observability stacks that large organizations already run internally.
Finally, the detailed Prometheus metrics and health-endpoint guidance—particularly the advice to gate autoscaling logic on a `connected` field rather than raw queue counts, to avoid stale metrics from disconnected replicas driving bad scaling decisions—reflects lessons learned from operating distributed systems at scale. This level of specificity around autoscaling correctness (queue-depth vs. capacity-based scaling, HPA/KEDA integration) positions Claude Code's self-hosted runner as infrastructure meant to sit inside existing enterprise Kubernetes and cloud-native observability stacks. Collectively, this reference illustrates a broader trend in enterprise AI tooling: as coding agents move from experimental products to production-critical infrastructure, vendors like Anthropic must build not just capable models but also the mundane, exacting operational tooling—health checks, metrics, secret rotation, autoscaling semantics—that enterprises require before they'll trust AI agents to run continuously against their private codebases.
Read original article →