Self-Hosted Claude Code Environments: Runners in Your Network

Three parts:

• Environment: a named destination created on the Cloud environments admin page in claude.ai. It groups a set of runners and appears in the environment picker next to Anthropic-hosted environments.
• Runner: the long-lived process you deploy on Linux or macOS hosts or containers. It is part of the standard claude binary (claude self-hosted-runner, v2.1.224 or later). It authenticates with the environment's secret, registers, and polls for work.
• Session: one Claude Code task. When a developer picks your environment, Anthropic's control plane queues the session; a runner with free capacity claims it, clones the repository, and starts a child Claude Code process that streams events back over HTTPS.

Every connection is outbound from your network: queue polling, the event stream, and model inference go to api.anthropic.com, and the runner reaches your git host with credentials you configure. Anthropic never connects in. Corporate egress proxies are supported through the usual HTTPS_PROXY and NO_PROXY variables, but because session streaming uses server-sent events, a proxy in the path must not buffer responses.

You can keep runners running yourself, or deploy Anthropic's autoscaling orchestrator, which starts runners as sessions queue.

This is the part to get exactly right in a compliance review. Per the docs:

• Stays on your machines: repository checkouts, build artifacts, secrets, and any files a session creates or modifies.
• Goes to Anthropic: the conversation itself (prompts, responses, and tool results) goes to api.anthropic.com, and Anthropic stores the session transcript so the session can be resumed from other surfaces. Session orchestration, queueing, and the claude.ai interface remain Anthropic-hosted.

Model inference uses the Anthropic API by default. You can configure a runner to send model requests to Amazon Bedrock or Google Cloud's Agent Platform instead, but session content still goes to Anthropic in the session's event stream either way, and on such a runner server-managed settings and organisation policies from claude.ai do not reach sessions.

So self-hosting is about execution locality (network reach, tooling, where code and artifacts live), not about keeping prompts or tool output off Anthropic's systems. Organisations with Zero Data Retention or the HIPAA configuration cannot use self-hosted environments at all.

Prerequisites: an Owner turns on Allow self-hosted environments on the Cloud environments admin page (which requires cloud sessions to be enabled), the GitHub connector is on, the host has outbound HTTPS to api.anthropic.com and your git host, Git 2.24 or newer, and a clock synchronised with NTP (authentication fails if it is more than five minutes off). Windows is not supported as a runner host.

Check the binary first:

1claude self-hosted-runner --help

Then either run the guided setup, claude self-hosted-runner setup, as an Owner, or do it manually:

1. On the Cloud environments page, select New, name the environment, and copy the environment key. It is shown once and expires 365 days after creation. 2. Save it to a file readable only by the runner's user, without putting it in shell history:

1mkdir -p /etc/claude2(umask 077 && cat > /etc/claude/environment-secret)

3. Start the runner with a dedicated working directory:

1claude self-hosted-runner \2  --environment-secret-file /etc/claude/environment-secret \3  --base-dir /srv/claude-runner

The runner logs Registered: runner_id=... and the environment's status changes to Healthy. Start a session at claude.ai/code, pick your environment and a repository the host can clone over HTTPS, and the runner logs Picked up session ....

Three behaviours shape how you deploy runners.

One owner at a time. The first session a runner picks up locks it to that session's owner (the user, or the Claude Tag agent for channel sessions). It then runs sessions only for that owner, up to --capacity. This keeps checked-out code from mixing between people. It also means your minimum fleet size is the number of owners active at once.

Leases by polling. A runner holds a lease on each session, refreshed by every poll, which doubles as its heartbeat. If polling stops, the lease lapses after about 60 seconds and the session can be requeued to another runner, which can take several minutes.

Exit by design. At the default --drain-grace-sec 0, a runner exits as soon as its sessions finish, so an orchestrator such as Kubernetes can restart it with a fresh disk, ready for any owner. Run runners under something that restarts them and backs off when a runner exits immediately after start. If your infrastructure kills hosts at a known time without a usable SIGTERM, such as spot reclamation or sandbox lifetime caps, pass --retire-at <epoch-seconds> a few minutes earlier: the runner stops taking work, releases sessions so they resume on a fresh runner at the user's next message, and exits cleanly.

The docs are clear that most teams are better served by Anthropic-hosted environments, which need no infrastructure. Self-hosting makes sense when your network, tooling, or compliance requirements call for execution on infrastructure you control, and you accept the operational ownership: building and maintaining the runner image, operating the fleet, and controlling its network.

Before production, Anthropic's deploy guide covers security hardening, egress control, git credential options (including per-session minted credentials and an Anthropic git proxy for github.com), and Kubernetes and Compose recipes. Treat the runner like CI infrastructure: it executes code chosen by whoever starts a session.

In a test Team or Enterprise organisation where you are an Owner:

1. Enable Allow self-hosted environments, create an environment, and save its key to a file with umask 077. 2. On a Linux VM, install Claude Code, check claude self-hosted-runner --help, and start the runner with a dedicated --base-dir. 3. Confirm Registered: runner_id=... and the Healthy status. 4. Start a session at claude.ai/code on a public repository, picking your environment, and watch for Picked up session .... 5. From another machine, send a follow-up: claude -p "list the files you changed" --cloud <session-id>. 6. Archive the session and observe the runner exit with account workload drained.

Pass criterion: the session ran on your VM, you can show from the VM which repository was checked out, and you can explain which parts of that session were still sent to Anthropic.