Skip to main content
Self-hosted environments are in public beta on Team and Enterprise plans and are off by default. See Availability and limitations for the enablement path and what’s excluded.
A self-hosted environment executes Claude Code cloud sessions on infrastructure your organization operates. A cloud session is any session that runs somewhere other than the developer’s machine: developers start them from claude.ai, the mobile and desktop apps, the terminal with claude --cloud, and scheduled routines, and by default they execute on Anthropic’s infrastructure. In a self-hosted environment, those same sessions execute inside your network, and the developer experience is otherwise the same apart from the differences in Availability and limitations and the deploy page’s known issues. If your team doesn’t use cloud sessions, there’s nothing here to configure: sessions in a terminal or IDE always run on the developer’s own machine. If you want to run Claude Code on your own always-on machine and drive it from other devices, use Remote Control, which is also available on Pro and Max plans. When you’re ready to set up, go straight to the quickstart; to review the security posture first, start with Deploy to production. The rest of this page explains how self-hosting works and when to choose it.

​
How self-hosted environments work

Self-hosting has three parts:
  • Environment: a named destination that cloud sessions can be sent to. Your organization creates environments in claude.ai admin settings, and each one groups a set of runners.
  • Runner: a program running on hosts inside your network. Runners execute the sessions; the idea is the same as a self-hosted CI runner.
  • Session: one Claude Code task a developer started.
When a developer starts a cloud session, the session-start UI shows an environment picker listing Anthropic-hosted environments alongside any your organization has created. If they choose yours, Anthropic’s control plane places the session on your environment’s queue, where a runner claims it, clones the repository the developer chose, and starts a Claude Code process on your host to run it. The runner authenticates to your git host with credentials you configure; Configure git covers the options. Sessions reach your internal services from inside your network, and your git host the same way when it’s internal; the traffic to Anthropic, queue polling, the session’s event stream, and model inference, is outbound HTTPS to api.anthropic.com, with the short list of further hosts sessions can reach in Network requirements. Anthropic never connects into your network.
Architecture diagram of a self-hosted environment: your network boundary contains a runner, two Claude Code session processes inside it, and your git host, with api.anthropic.com outside holding queue, session stream, and inference. The runner polls the queue and reaches the git host, each session process opens its own stream, inference, and git connections, and every connection is outbound from your network, with none inbound.
The two Claude Code boxes in the diagram are session processes: one runner executing two sessions at once, up to its configured capacity. A runner serves one user at a time, locking to that user’s account when it claims its first session, so checked-out code never mixes between users; Runner lifecycle covers the rule. You can start runners yourself and keep them running, or run the autoscaling orchestrator, a second process you host, which starts runners as sessions queue; each runner exits on its own when its work finishes. Either way, you set the environment up once, and it appears in the picker on every supported surface.

​
Availability and limitations

Check these before planning a rollout:

​
Why self-host

Most teams are better served by Anthropic-hosted environments, which need no infrastructure to run or maintain. Self-hosting is for teams whose network, tooling, or compliance requirements call for keeping session execution on infrastructure they control. If that’s you, plan for the operational ownership it carries: you build and maintain the runner image, operate the fleet, and control its network. In exchange, self-hosting gives you network access, custom tooling, and compliance control:
  • 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. Session content still goes to api.anthropic.com for model inference.

​
Environments, runners, and sessions

Environments are managed on the Cloud environments page in claude.ai admin settings; runners are processes you start and manage on your own infrastructure.

​
Key concepts

These terms appear throughout the self-hosted pages: In API fields, token claims, and metric names, the environment appears as pool, and the environment ID is the pool_id. The reference maps the two spellings, including the deprecated pool flag names. A runner serves one user at a time. The first session a runner picks up locks the runner to that user, and the runner then runs sessions only for that user, up to a configured capacity. The minimum fleet size is therefore the number of users you expect to be active at once.

​
Session lifecycle

When a developer starts a session and selects your environment, Anthropic’s control plane places the session on the environment’s queue. From there:
  1. A runner with free capacity claims the session and holds a lease on it.
  2. The runner 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.

​
Runner lifecycle

The first session a runner picks up locks the runner to the account of the user who started that session, and the runner runs up to --capacity concurrent sessions for that account. While the runner has active sessions, the runner keeps claiming the locked account’s queued work. What happens once they finish depends on --drain-grace-sec:
  • At the default of 0: the runner exits as soon as its active sessions finish, without polling for more, so the orchestrator you deploy it under, such as Kubernetes, can restart it with a fresh disk, ready to serve any account.
  • At a positive value: the runner keeps polling the locked account’s queue for that many seconds before exiting.
This lifecycle isolates each user’s checked-out code without requiring the runner to delete disk state between users. A kill that delivers SIGTERM needs no flag: the runner drains as Shutdown timing describes. If your infrastructure instead destroys hosts at a known wall-clock time without a signal, or with a grace period too short to drain, such as a sandbox lifetime cap or spot-instance reclamation, pass --retire-at <epoch-seconds> set to a few minutes before that time. At the retire time:
  1. The runner stops taking new work.
  2. The runner releases each active session through the same release path the --release-idle-session-min flag uses, so the session resumes on a fresh runner when the user sends their next message. A session that’s mid-turn is released as soon as that turn finishes; a session whose finished turn left background tasks running gets up to 60 seconds of grace before releasing anyway.
  3. The runner exits 0 once all its sessions are released.
A turn that outlives the kill is still lost; Shutdown timing covers sizing the margin. 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 to another runner.

​
Network paths

The runner and its sessions make several kinds of outbound connection, and no inbound connectivity from Anthropic is required:
  • Control plane: the runner polls api.anthropic.com for work and posts setup-progress and failure events, all outbound HTTPS. Polling doubles as the runner’s heartbeat.
  • SCM connector: the optional orchestrator SCM connector tunnel is the only WebSocket connection.
  • Git: the runner clones from and pushes to your git host over HTTPS or SSH, authenticated with credentials your deployment provides; Configure git covers the options, including per-session minted credentials and the Anthropic git proxy, which routes git through api.anthropic.com instead.
  • Session child: the child Claude Code process holds the session’s event stream to api.anthropic.com, and makes its own outbound calls for model inference and for git commands run during the session. See Network requirements for the full egress list. The diagram above shows these paths, apart from the optional SCM connector.
Model inference uses the Anthropic API. The control plane delivers the API endpoint to each session, and the session authenticates with an Anthropic-issued, session-scoped OAuth token, so inference can’t be routed through Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, or an LLM gateway in self-hosted environments. Corporate egress proxies are supported. The runner and the optional autoscaling orchestrator honor the proxy and mTLS environment variables described in Network configuration, such as HTTPS_PROXY and NO_PROXY; set them in each process’s environment. The variables cover control-plane calls, the orchestrator’s SCM connector WebSocket, and the built-in clone for HTTPS remotes, and sessions inherit them from the runner. Session streaming uses server-sent events over HTTPS, so a proxy in the path must not buffer responses.

​
What stays on your infrastructure

Repository checkouts, build artifacts, secrets, and any files a session creates or modifies stay on the machines you provision. The conversation itself, including prompts, responses, and tool results, goes to api.anthropic.com for model inference, and the session transcript is stored by Anthropic so a session can be picked up from any surface. Session orchestration, queueing, and the claude.ai interface remain Anthropic-hosted: a self-hosted environment moves session execution into your network, not the control plane.

​
Get started

The self-hosted environments pages are organized by what you’re doing:
  • Quickstart: install Claude Code, create an environment, start a runner, and route your first session
  • Deploy to production: security hardening, network egress, git credentials, Kubernetes and Compose recipes, known issues, and troubleshooting
  • Customize sessions: wrapper scripts for per-session credentials, lifecycle hooks, on-demand runners, MCP servers, and permissions
  • Test end to end: a CI smoke test that verifies a runner image before you promote it
  • Reference: every CLI flag, environment variable, metric, and the health endpoint
  • Verify session identity: validate the session token from your own services before granting access