Claude Code Self-Hosted Runners: Cloud Sessions, Your Box

The objection I hear most often to cloud coding sessions is not about the model. It is that the repository has to leave the building, and for a lot of teams that ends the conversation before it starts. Self-hosted environments are the answer to that specific objection, and the shape of the answer is worth understanding precisely, because it solves less than people hope and more than they expect.

This post covers the three-part architecture, the network paths that make it a genuine security story, the runner lifecycle rule that determines your fleet size, and the exclusion list that decides whether you can use it at all — which is the section to read first, because several of the exclusions are dealbreakers.

Three parts, and only one of them is yours to run

The vocabulary matters here because the docs use it consistently and the concepts do not map onto CI intuitions cleanly:

• An environment is a named destination that cloud sessions can be sent to, created in claude.ai admin settings, grouping a set of runners. In API fields and metric names it appears as a pool.
• A runner is a long-lived process you deploy on hosts inside your network. It registers with the environment, receives a token, and polls for sessions — the same idea as a self-hosted CI runner.
• A session is one Claude Code task a developer started, running as a child process the runner spawns.

When a developer starts a cloud session, the picker lists Anthropic-hosted environments alongside yours. Choose yours and the control plane places the session on your environment's queue, where a runner claims it, clones the repository, and starts the work. The control plane stays Anthropic-hosted throughout — session orchestration, queueing and the claude.ai interface are not things you are self-hosting.

Everything outbound, nothing inbound

This is the part that makes the security review straightforward. The runner and its sessions make several kinds of outbound connection and require no inbound connectivity at all. That is a materially easier conversation than a self-hosted CI runner that needs a webhook endpoint, and it is worth leading with when you take this to a network team.

# Every connection is OUTBOUND. Anthropic never connects
# into your network — there is no inbound port to open.

  your network
  ├─ runner ──────────► api.anthropic.com   (poll queue, post events)
  │                                          the poll IS the heartbeat
  ├─ runner ──────────► your git host        (clone / push, HTTPS or SSH)
  ├─ session child ───► api.anthropic.com   (event stream + inference)
  └─ session child ───► your internal services, databases, registries

# Corporate egress proxies are supported: the runner and the
# autoscaling orchestrator honour HTTPS_PROXY and NO_PROXY, and
# sessions inherit them. Session streaming is server-sent events
# over HTTPS, so a proxy in the path MUST NOT buffer responses.

One runner, one user, and what that does to your fleet size

This is the rule that decides your capacity planning, and it is not obvious from the outside. A runner serves one user at a time: the first session it claims locks it to that user's account, and it then runs only that account's sessions up to its configured capacity. The purpose is isolation — checked-out code never mixes between users, without the runner having to scrub disk state between them.

# A runner serves ONE USER AT A TIME. The first session it
# claims locks it to that user's account, so checked-out code
# never mixes between users. That single rule sets your fleet
# size: minimum runners = users active at once.

--capacity <N>            # concurrent sessions for the locked account

--drain-grace-sec 0       # DEFAULT: exit as soon as active sessions
                          # finish, so your orchestrator restarts it
                          # with a fresh disk, ready for any account
--drain-grace-sec 300     # keep polling the locked account for 5 min

--retire-at <epoch-secs>  # for hosts destroyed at a known wall-clock
                          # time with NO signal — spot reclamation, a
                          # sandbox lifetime cap. Set it a few minutes
                          # before the kill.

# Without --retire-at, a signal-less host kill is indistinguishable
# from a crash: the control plane records a lost worker rather than
# a clean release, and the session requeues elsewhere.

The consequence is that your minimum fleet size is the number of users you expect to be active at once, not the number of concurrent sessions. Five developers each running one session need five runners; one developer running five sessions needs one runner with a capacity of five. Getting this backwards is the fastest way to under-provision a pilot and conclude the feature is slow.

The session lifecycle, and what happens when a host dies

Knowing the lease mechanics turns most runner debugging into arithmetic:

1. A runner with free capacity claims the session and holds a lease on it.
2. It clones the repository into its working directory and spawns a child Claude Code process.
3. The child streams events back over HTTPS while the runner keeps polling — each poll refreshes the lease and doubles as the heartbeat.
4. If the runner stops polling for about 60 seconds, the server requeues the session for another runner.

What stays with you, and what does not

Being precise here is the difference between a security review that passes and one that stalls. The boundary is real but it is not total, and overselling it is the fastest way to lose credibility with a reviewer who reads the docs.

Where each thing actually lives:

The exclusions to check before you plan anything

Read this list first. Several entries are hard stops, and one of them rules out a whole class of enterprise deployment:

• Public beta on Team and Enterprise plans only, off by default, and an Owner must enable it on the cloud environments admin page — which itself requires Claude Code on the web to be enabled for the organisation.
• Unavailable for organisations with Zero Data Retention enabled.
• Inference uses the Anthropic API and cannot be routed through Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an LLM gateway. If your entire reason for self-hosting is keeping inference on your cloud contract, this is the wrong feature.
• Sessions check out repositories from GitHub, and Claude Tag, Claude Security and Code Review sessions do not route to self-hosted environments yet.

When self-hosting is worth the operational weight

Most teams are better served by Anthropic-hosted environments, which need no infrastructure to run or maintain. Self-hosting means you build and maintain the runner image, operate the fleet, and control its network — real, permanent operational ownership in exchange for three things: sessions that reach internal services without exposing them publicly, a runner image with your compilers and internal CLIs pre-installed, and checkouts that stay on machines you control.

If your team does not use cloud sessions at all, there is nothing here to configure — terminal and IDE sessions always run on the developer's own machine. And if what you actually want is to run Claude Code on your own always-on box and drive it from other devices, that is Remote Control, which is available on Pro and Max too and needs none of this.

Self-hosted environments are a well-shaped answer to a narrow question: can cloud sessions run where our code already lives. They answer it convincingly, with an all-outbound network model that survives a security review. They do not answer where inference happens, they do not work under Zero Data Retention, and they carry the ongoing cost of a fleet you now operate. Decide whether the narrow question is the one you actually have before building anything.