Here's the short version, up top, because that's what you came for. As of Claude Code v2.1.224 (August 7, 2026), you can run Claude Code cloud sessions on machines your organization controls instead of on Anthropic's compute. The command is claude self-hosted-runner, it's in public beta on Team and Enterprise plans, and the shape is three parts: an environment (a named queue you create in claude.ai admin settings), runners (long-lived processes you deploy inside your network that claim sessions), and sessions (one task each). The one rule that will shape your rollout: a runner serves one user at a time, so your minimum fleet size is the number of users you expect active at once.
Now the reasoning, and the setup.
What "cloud session" actually means here#
This feature only touches cloud sessions — and that word is doing real work. A cloud session is any Claude Code session that runs somewhere other than the developer's own laptop: one started from claude.ai, the mobile and desktop apps, the terminal with claude --cloud, or a scheduled routine. By default those execute on Anthropic's infrastructure.
If your team runs Claude Code the old way — in a terminal or IDE on each developer's machine — there is nothing here to configure. Those sessions already run on the developer's own hardware. Self-hosting is specifically about taking the cloud sessions, the ones that would land on Anthropic's compute, and landing them on yours instead. The developer experience is otherwise the same: they pick your environment from the session-start menu and keep working.
Why you'd want this (and why most teams shouldn't)#
Anthropic's own guidance is refreshingly blunt: most teams are better served by the hosted default, which needs no infrastructure to run or maintain. Self-hosting is for teams whose network, tooling, or compliance requirements make it worth the operational ownership. What you get in exchange:
- Network access. Sessions run inside your network and can reach internal services, databases, and registries without exposing them to the public internet.
- Custom tooling. Pre-install compilers, SDKs, and internal CLIs in your runner image so every session starts ready to build.
- Compliance. Repository checkouts and build artifacts stay on infrastructure you control.
The cost side is real: you build and maintain the runner image, operate the fleet, and control its network. If none of the three benefits above is a hard requirement, the hosted default is the cheaper call — the same way renting beats self-hosting until utilization or control tips the math.
The three layers#
| Layer | What it is |
|---|---|
| Environment | A named destination sessions get routed to. You create it in claude.ai admin settings; it groups a set of runners. In API fields it appears as a pool, and its id is the pool_id. |
| Runner | A long-lived process you deploy on hosts inside your network. It registers with the environment using the one-time environment key, receives a runner token, and polls the queue for work — the same idea as a self-hosted CI runner. |
| Session | One Claude Code task a developer started. When a runner claims it, it clones the chosen repository and spawns a child Claude Code process to run it. |
Setup, end to end#
- Enable it. An Owner or admin turns on Allow self-hosted environments on the Cloud environments admin page in claude.ai settings. Claude Code on the web must already be enabled for the org. (Not available with Zero Data Retention.)
- Create an environment. Still in admin settings, create a named environment. It hands you an environment key — the single shared credential runners use to register — shown once. Save it in your secret manager now.
- Deploy a runner. On a host inside your network, install Claude Code and start the runner, giving it the environment key and a concurrency cap:
# on a machine inside your network
npm install -g @anthropic-ai/claude-code
export CLAUDE_ENV_KEY="…" # the one-time key from step 2
claude self-hosted-runner \
--capacity 2 \ # concurrent sessions this runner serves
--drain-grace-sec 0 # exit on drain so a fresh disk serves the next userThe runner registers, receives its runner token, and starts polling api.anthropic.com for queued sessions. Each poll doubles as its heartbeat.
- Route a session. When any developer starts a cloud session, the session-start picker now lists your environment alongside Anthropic-hosted ones. They pick yours; the control plane places the session on your queue; a runner claims it, clones the repo, and runs it inside your network.
For production you'll want the deploy guide — it covers git credentials, the full network-egress list, and Kubernetes and Compose recipes. If you don't want a fixed warm fleet, run the autoscaling orchestrator: a second process you host that starts runners as sessions queue, each exiting on its own when its work finishes.
The rule that sizes your fleet#
This is the detail that surprises people, so front-load it in your capacity planning: a runner serves one user at a time. The first session a runner picks up locks it to that user's account, and it then runs only that user's sessions — up to --capacity concurrent — until it drains. That isolation is how checked-out code never mixes between users without wiping disk between them.
The consequence: your minimum fleet size is the number of users you expect active at the same time, not the number of sessions. Two developers each running two sessions is two runners at --capacity 2, not one runner at four. The lifecycle knobs tune the rest:
--drain-grace-sec 0(default): the runner exits as soon as its active sessions finish, so an orchestrator like Kubernetes restarts it with a fresh disk, ready to serve any account.--drain-grace-sec <n>: the runner keeps polling the locked account's queue fornmore seconds before exiting — worth it if one developer starts sessions in bursts.--retire-at <epoch-seconds>: for hosts killed at a known wall-clock time without a signal (spot reclamation, sandbox lifetime caps). The runner stops taking new work at that time and cleanly releases active sessions so they resume on a fresh runner.
If a runner stops polling for about 60 seconds, the server assumes it's gone and requeues its session to another runner.
What leaves your network, and what doesn't#
The whole point is control over where code and artifacts live, so be precise about the boundary:
Stays on your machines: repository checkouts, build artifacts, secrets, and any files a session creates or modifies. Sessions reach your internal services directly.
Still goes to Anthropic: the conversation itself — prompts, responses, and tool results — travels to api.anthropic.com for model inference, and the session transcript is stored by Anthropic so a developer can pick the session back up from any surface. Model inference uses the Anthropic API with a session-scoped OAuth token; in a self-hosted environment it cannot be routed through Amazon Bedrock, Google's Vertex/Agent Platform, Microsoft Foundry, or an LLM gateway.
Critically, every connection is outbound HTTPS — the runner polling for work, the session's event stream, git, and inference. Anthropic never opens a connection into your network. Corporate egress proxies are supported via the usual HTTPS_PROXY / NO_PROXY variables.
When to reach for this vs. Remote Control#
One common confusion: if you just want to run Claude Code on your own always-on machine and drive it from your phone or another laptop, that's Remote Control, not this — and Remote Control works on Pro and Max too. Self-hosted environments are an organization-level feature for routing many developers' cloud sessions, across every surface, onto a fleet your org operates. One person, one machine → Remote Control. A team that needs session execution to stay inside a controlled network → self-hosted environments.
If you're still deciding which Claude Code surface your team should standardize on in the first place, start with our guide to picking a parallel coding-agent runner — self-hosting is a deployment choice you layer on after you've picked how your team runs agents, not instead of it.
