Claude Code: Self-Hosted Environments: Points: 1 # Comments: 0

What happened

Anthropic has published an official quickstart guide for self-hosted environments in Claude Code, giving organizations on Team and Enterprise plans a documented path to running Claude Code cloud sessions on infrastructure they control. The guide walks through four sequential steps — creating an environment in the admin UI, writing a secret to the runner host, starting the runner process, and routing a test session — and ends with commands for sending follow-up messages from the CLI.

This piece unpacks what self-hosted environments are, how the runner-polling model works technically, who needs this feature and why, and what builders should verify before pushing any configuration into production. If you manage developer tooling for a company with strict data-residency requirements or private network resources, this is aimed at you.

Anthropic has released a public beta of self-hosted environments for Claude Code, available on Team and Enterprise plans. The feature lets an organization's administrators create a named environment in the Cloud environments admin page at claude.ai/admin-settings/cloud-environments, generate an environment secret, and then point runner processes at that secret so Claude Code cloud sessions execute on machines the organization controls rather than on Anthropic-hosted infrastructure. The quickstart documentation covers the minimal one-runner, one-host setup, while companion pages handle fleet hardening, Kubernetes and Compose orchestration, egress control, and git credential management. The feature is listed as public beta, and its availability and enablement path are gated behind the Cloud environments admin page.

How it works

The first step inside any organization is for someone holding an Owner role to toggle Allow self-hosted environments on that admin page. Until that toggle is set, the New button for creating an environment does not appear. From that point the workflow is procedural: create the environment, copy the environment secret once — the admin UI shows it only once, and it expires after 365 days — then move to the runner host and begin the terminal steps.

The runner is not a separate binary. It is a subcommand baked into the standard claude binary at version 2.1.224 or later. On older versions the subcommand silently falls through to general help output, so a version check is the documented first verification step. Running claude self-hosted-runner --help on a ready host prints the runner's own usage text including flags such as --environment-secret-file. The runner reads the environment secret from a file — written with a umask of 077 so only the owning process can read it — and begins polling Anthropic's infrastructure for queued sessions. When a session is routed to the environment from claude.ai/code, the next available runner picks it up, logs Picked up session with the session ID, clones the selected repository using whatever git credentials the host already has, and executes Claude Code in that checkout.

Why it matters

The runner host must be Linux or macOS, since Windows is not supported as a runner host. It needs outbound HTTPS to api.anthropic.com and to claude.ai, plus access to the git host for cloning. The clock must be synchronized to within five minutes of real time, because the authentication token validation rejects clock skew beyond that threshold. When a runner finishes its active sessions it exits by design, so production deployments are expected to run the runner under an orchestrator — Kubernetes or Compose, per the deploy guide — that restarts it on exit, typically with a fresh filesystem per restart.

The core reason organizations request self-hosted execution is data residency: code, prompts, and model replies stay on infrastructure the organization audits, rather than passing through Anthropic-managed compute. Teams in regulated industries — finance, healthcare, government contracting — often cannot route source code through a third-party cloud execution tier regardless of contractual controls. Self-hosted environments give those teams a path to Claude Code that their security and compliance teams can approve, since the runner host is in their own network with their own egress controls and logging. A session can also reach internal services, private package registries, and VPN-accessible repositories that Anthropic-hosted runners cannot.

The session routing model is also notable from a developer experience standpoint. Developers still start sessions from claude.ai in a browser and do not interact with the runner host directly. Self-hosted environments appear in the same environment picker alongside Anthropic-hosted ones, so from the developer's view the surface is identical. Follow-up messages can be sent from any machine where the developer is signed in with claude auth login by running claude -p with the --cloud flag and a session ID, without needing to be on the runner host.

Who is affected

The feature directly affects platform and infrastructure teams at organizations on Team or Enterprise plans who are responsible for controlling where AI-assisted development tasks execute. They are the ones who must enable the toggle, create environments, manage secret rotation, and build or configure the orchestrator that keeps runners alive. Organizations already running Claude Code through the Anthropic-hosted path are not forced to migrate; self-hosted environments are an opt-in addition to the existing offerings in the environment picker.

Individual developers are affected in a narrower way: their sessions may silently move to a different execution host when their organization's administrator routes a project to a self-hosted environment, but the claude.ai/code interface they use does not change. Developers who want to send programmatic follow-ups need a session ID — either the bare session_ or cse_-prefixed form or the full claude.ai/code URL — which the runner logs when it picks up the session. Teams building CI pipelines around Claude Code are a distinct audience: the testing companion page covers dispatching sessions from CI and reading Claude's replies, which requires knowing the environment's ccpool_-prefixed ID that remains visible in the environment detail dialog after the secret has been shown and dismissed.

What to watch next

Several behaviors are worth verifying before treating this as production-ready. Environment secrets expire after 365 days from creation with no automatic renewal: administrators should build a rotation procedure now, because runners holding a revoked or expired secret fail their next authenticated poll and exit logging poll auth failed. The runner's --base-dir flag controls where repository checkouts land; without it the runner falls back to /workspace, which only works if that path already exists and is writable. A builder should confirm the base directory path is explicitly set in whatever systemd unit, Compose service, or Kubernetes pod spec manages the runner, rather than relying on the fallback.

The deploy guide pages covering egress control, git credential configuration, and token verification via the aud claim on the ccpool_ ID are listed as prerequisite reading before connecting real repositories or internal systems. The guided setup subcommand claude self-hosted-runner setup exists to automate much of this and writes a cheat sheet to ./runner-setup/CHEAT-SHEET.md, but it requires an interactive session and an account with the Owner role, so CI-only environments or hosts without an interactive terminal must use the manual steps. Watch for updates to the availability and limitations page as the public beta matures and any plan-level or capacity constraints are clarified.