Claude Code Self-Hosting Makes Platform Engineering the Agent Runtime
Rohit Ramachandran
Claude Code Self-Hosting Makes Platform Engineering the Agent Runtime
Ask an enterprise architect where Claude Code runs now, and the accurate answer can be: on our infrastructure and inside Anthropic's service.
That is not wordplay. Anthropic's new self-hosted environments for Claude Code move the execution of cloud sessions onto customer-operated machines or containers. Repository checkouts, build artifacts, local secrets, and files created by the session can stay on that compute. But Anthropic still runs the queue and session control plane, stores the transcript, and performs model inference. Prompts, responses, and tool results cross the boundary—and tool results can contain code Claude read.
The public beta, announced on August 6 for Team and Enterprise customers and shipped in Claude Code 2.1.224 on August 7, is therefore not an on-premises Claude stack. It is a bring-your-own-compute execution layer for Claude Code's existing cloud-session product.
That distinction makes the launch more important, not less. A developer can start work from the web, mobile, desktop, a routine, or the terminal and choose a company-operated environment without learning the fleet underneath. The platform team now owns that fleet's image, network, identity, capacity, recovery, and incident response.
The obvious benefit is private-network access. The less obvious shift is organizational: Claude Code is becoming enterprise agent infrastructure, and the environment—not the laptop—is becoming its scheduling primitive.
Put “self-hosted” on trial
The useful way to evaluate this product is to split it into four planes instead of drawing one box labelled “our VPC.”
A self-hosted session crosses four ownership zones. The arrows into the customer network are work claims made over outbound connections, not inbound Anthropic control connections.
The architecture documentation is unusually direct about these boundaries. A developer selects a named environment. Anthropic places the session on that environment's queue. A runner polls for work, claims the session, clones the selected repository, and starts a child Claude Code process. The runner and child connect outward to api.anthropic.com; Anthropic does not need an inbound connection into the customer network.
That outbound-only topology is useful for firewall design. It is not a data-residency promise. Model inference and the session event stream still leave the network.
| Layer or data | Where it lives or runs | Practical consequence |
|---|---|---|
| Repository checkout, build artifacts, modified files | Customer runner | Can reach private dependencies and remain on customer-operated storage. |
| Queue, environment selection, session orchestration | Anthropic control plane | The customer operates workers, not the global scheduler or interface. |
| Prompts, responses, and tool results | Sent to Anthropic | Tool results can carry source code or internal-service output across the boundary. |
| Session transcript | Stored by Anthropic | The same session can be resumed from multiple surfaces, but this is not a ZDR path. |
| Model inference | Anthropic API | Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and LLM gateways are not supported for these sessions. |
| Git, cloud, database, and registry credentials | Customer responsibility | Broad credentials in a runner image become available to model-directed code. |
| Claude.ai connectors such as Slack or Linear | Called from Anthropic's side | Connector traffic does not originate inside the runner's network boundary. |
This fact pattern should stop two common procurement shortcuts.
First, “our source stays local” is too broad. The checkout and artifacts can stay local; model-visible content does not necessarily do so. Second, “we use our cloud” is incomplete. The customer pays for and operates the runner compute, while Claude Code usage is consumed the same way as in Anthropic-hosted environments.
The economic case is access to private systems, a controlled toolchain, and customer-chosen execution policy—not automatically cheaper inference.
The scheduler carries the master key
Anthropic documents two fleet shapes: fixed runners and an on-demand orchestrator. They look like scaling choices. They are also different trust models.
Every named environment has a shared environment secret. That secret can register runners and claim sessions queued in that environment for any member of the organization. In a fixed fleet, the secret exists on the same kind of host that executes model-directed code. Anthropic's production guide tells operators to assume session code can read it and rotate it after suspected compromise.
The on-demand design changes the placement of authority. A separate orchestrator holds the environment secret, watches for a queued session with no available runner, and invokes a customer spawn-runner hook. The spawned runner receives a single-use work order rather than the reusable environment secret. It can run one session and be destroyed.
That makes the orchestrator the real root of trust. It decides which image starts, where it starts, which network policy surrounds it, and when the runtime disappears. The runner is deliberately disposable.
There is a second identity boundary inside the session. Anthropic supplies a signed session token that can identify the environment and session creator. The identity guide is careful about what this proves: Anthropic issued the token for that session; it does not prove which process on the runner is presenting it. Any code or tool inside the session can read the token.
The safe pattern is therefore not “turn the user's identity into full user credentials.” It is “verify the token, then mint the narrowest credential one coding session needs.” Short lifetime, one repository, one registry, one role, one task.
Capacity is counted in people
The fleet math contains a trap that generic worker-pool dashboards will miss.
A runner locks to the account behind the first session it claims. Raising --capacity lets that runner execute more sessions for the same user; it does not allow the runner to multiplex another active user. Anthropic states the consequence plainly: the minimum fleet size starts with the number of users expected to be active at once.
For a 500-seat rollout, “we average 40 concurrent tasks and each runner has capacity four” does not imply ten runners. If 35 people each have one active task, the floor is closer to 35 available user locks. Higher capacity helps when one developer fans out several sessions; it does nothing for a queue belonging to someone else.
Recovery markers: about 60 seconds without polling can requeue a leased session; a clean SIGTERM shutdown path may need up to 80 seconds at default settings.
This is closer to a fleet of per-user devboxes than a bag of stateless build workers. Useful capacity metrics include queued sessions by account, locked-account distribution, pickup latency, initialization time, active sessions, and last_poll_age_seconds. CPU utilization alone will tell a misleading story.
The beta's biggest gap is authorization
Any member of an Anthropic organization can dispatch a session to any self-hosted environment in that organization. The beta has no per-environment access control for dispatch. --lock-to-account can restrict which account a particular runner serves, but it does not change who can target the environment.
That makes organization membership an effective code-execution entitlement against every network zone connected to those environments.
For a small company with one engineering trust domain, this may be manageable. For a global enterprise with contractors, acquisitions, regulated divisions, production operators, and multiple identity systems, it is a serious design constraint. A “payments-prod” environment cannot safely rely on its friendly name to keep a contractor from selecting it.
Until finer-grained authorization exists, teams may need separate Anthropic organizations, physically low-trust runner networks, or environments with credentials and connectivity safe for the least-trusted organization member.
This limitation is more consequential than the absence of a polished autoscaling chart. It decides who can ask your infrastructure to run model-directed code.
Repository locality can still create a compliance regression
Self-hosted execution improves one part of the residency story while narrowing others.
The feature is unavailable to organizations with Zero Data Retention enabled. Anthropic stores the session transcript so work can be resumed across surfaces. Inference must use the Anthropic API; it cannot be routed through Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an enterprise LLM gateway. A corporate HTTPS proxy is supported, but a proxy is not a substitute for an approved model endpoint, regional provider, or gateway policy layer.
Only GitHub repository checkout is documented for the beta. Native Windows runner hosts are not supported; Anthropic recommends a Linux container on Windows. Claude Tag, Claude Security, and Code Review sessions do not yet route to self-hosted environments. The product announcement says support for excluded surfaces will follow separately, without dates.
The right architecture review starts with a residency matrix, not a runner proof of concept:
execution locality customer compute
repository and artifacts customer storage
model-visible content Anthropic API
transcript Anthropic storage
session scheduling Anthropic control plane
connector execution Anthropic side for claude.ai connectors
inference route first-party Anthropic only
An enterprise that requires Bedrock billing, a Foundry endpoint, a central LLM gateway, or ZDR may find that the “self-hosted” option fits worse than ordinary local Claude Code. That is not an edge case. It is the exact kind of policy conflict a self-hosting label tends to hide.
Ephemeral runners inherit CI's failure modes—and add session state
Anthropic explicitly borrows the self-hosted CI-runner model. The analogy is useful because the hard lessons already exist. GitHub recommends ephemeral self-hosted runners for autoscaling and warns that a persistent runner compromised by untrusted code can receive future jobs. Claude Code adds a longer-lived conversational session and a model choosing commands, which makes cleanup and recovery even more important.
Anthropic recommends fresh per-session containers or VMs with --capacity 1, the default zero drain grace, and destruction after the runner exits. It also recommends default-deny egress, least-privilege host IAM, blocked cloud metadata access, read-only runner configuration, and per-session credentials.
Those are production requirements, not decorative hardening tips. The default repository-settings guard is warn, which logs a risky committed setting and still starts the session. The product cannot enforce customer network egress. Restarting a Docker container can reuse its writable layer. A basic /healthz response proves the process is alive, not that it is still polling; operators need the poll-age metric to catch that failure.
Recovery needs its own test plan. If a runner stops polling for roughly 60 seconds, the control plane can requeue the session to another runner. The new runner clones the starting branch again. Unpushed work can disappear. --push-outcome-on-release can preserve committed work on a best-effort basis, but it does not save a dirty working tree or per-session shell and configuration state. Anthropic also warns operators to protect claude/* refs because resume fetches the prior outcome branch without verifying who pushed it.
Shutdown is another quiet source of failure. A runner receiving SIGTERM may need up to 80 seconds for its default shutdown path, while Kubernetes defaults to a 30-second termination grace period. At the default --drain-wait-sec 0, a rolling restart does not wait for an in-flight turn. The similarly named --drain-grace-sec 0 controls whether an idle, user-locked runner waits for more work before exiting. Confusing the flags can turn a routine deployment into lost work.
The Git branch, runner image, and termination budget are now part of session integrity.
Best when standard cloud tooling and Anthropic's network boundary fit. Anthropic operates the runtime; private services and custom hardware are the tradeoff.
Fastest path to customer-network execution, but the reusable environment secret sits on hosts that run model-directed code. Treat the fleet as a low-trust zone.
Keeps the environment secret on a non-executing orchestrator and destroys session hosts, in exchange for more image, scheduler, startup, and observability work.
Why the rest of 2.1.224 belongs in this story
The runner command was not the only infrastructure change in Claude Code 2.1.224. The release also added cross-session SendMessage with ListAgents discovery on macOS and Linux, archive plugin sources fetched as HTTPS ZIP files with optional SHA-256 pinning, and structured credential-masking controls. It fixed a filesystem-deny bypass caused by trailing slashes and a session-directory collision affecting very long project paths.
These are adjacent capabilities, not proof that self-hosted sessions already form a documented multi-agent cluster. Anthropic has not published a complete reference for cross-session discovery, authentication, ordering, retention, or trust-zone behavior. Pilot messaging separately from runner rollout.
Still, the bundle reveals the direction of travel. Once sessions can move across surfaces and machines, communicate with peers, install packaged capabilities, and execute inside enterprise networks, runner lifecycle is only one part of the system. Message delivery, plugin provenance, credential handling, filesystem separation, and approval policy become one operational problem.
SHA-256 pinning is a good example of the distinction enterprises must keep making. A digest proves the downloaded bytes match a chosen digest. It does not prove who published the archive or who approved it. A useful provenance record also needs source identity, resolved plugin contents, hooks and executables, approver, runner-image digest, and the policy that allowed installation.
The RohitAI read: environment IDs become execution classes
RohitAI's earlier analysis of Codex remote Code Mode argued that moving an executor behind a protocol creates a useful seam without creating a complete remote-agent product. Anthropic now packages more of that missing envelope: user-facing environment selection, queueing, repository checkout, runner claims, session recovery, fixed and on-demand fleet modes, health metrics, and identity tokens.
The closest contrast is AWS AgentCore, where AWS turns each session into a managed cloud resource and owns dedicated microVM isolation and scaling. Anthropic keeps the session interface, control plane, transcript, and inference while handing the runtime fleet to the customer. Neither arrangement is universally better. They sell different ownership boundaries.
The durable change is that an environment ID can now act like an execution class:
mobile request ───────┐
desktop session ──────┤
web task ─────────────┼──> environment policy ──> runner class
scheduled routine ────┤
terminal dispatch ────┘
The developer chooses “payments-build” or “gpu-ci,” not a pod, VPC, AMI, credential broker, or Git clone strategy. Platform engineering maps that friendly destination to a hardened runtime and policy set.
Three consequences follow.
Per-environment authorization should become table stakes. Organization-wide dispatch conflicts with ordinary enterprise segmentation. Runner groups, repository allowlists, and identity-aware dispatch controls are the most predictable route from public beta to broad production use.
Kubernetes and infrastructure-as-code will become adoption layers. Anthropic documents manifests, hooks, Prometheus metrics, and an orchestrator, but the customer still assembles the system. The current absence of a documented first-class Terraform resource for environment policy, fleet identity, or dispatch rights is conspicuous next to the governance pattern we covered in OpenAI's Terraform provider.
The session needs an attention console. A task can begin on one surface, execute elsewhere, be requeued after a lost runner, request approval, and potentially exchange messages with another session. Microsoft's Agent Host work already points toward sessions as durable work objects. Enterprise operators will want one place to see queue age, identity, environment, messages, approvals, cost, commits, failures, and trust-zone crossings.
My medium-confidence prediction is that inference routing becomes a pressure point too. Companies that adopted Bedrock, Google, Foundry, or an LLM gateway specifically for regional, contractual, billing, or policy reasons will not forget those requirements because repository execution moved into their network.
A production pilot should try to break the handoffs
Do not evaluate this release by installing a runner and watching one clean pull request appear. The risky behavior happens at boundaries: a credential rotates, a user targets the wrong environment, a pod dies mid-turn, a plugin changes, a branch disappears, or the process remains alive while polling stops.
There is no launch benchmark for startup latency, queue throughput, task completion, security improvement, SLA, or cost per outcome. A responsible pilot measures those against the organization's own repositories and failure scenarios. This release changes where work runs and who operates it; it does not claim Claude became a better coder.
FAQ
Is Claude Code now fully self-hosted or on-premises?
No. Session execution runs on customer-operated compute, but Anthropic still hosts queueing, orchestration, the user interface, transcript storage, and model inference. Prompts, responses, and tool results go to the Anthropic API.
Does source code stay inside the customer network?
Repository checkouts, build artifacts, secrets, and files created or modified by the session stay on the runner infrastructure. But tool results sent for inference can include source code Claude reads. “The checkout stays local” is accurate; “no code can leave” is not.
Can self-hosted sessions use Bedrock, Google Cloud, Microsoft Foundry, or an LLM gateway?
No, not in the public beta. Anthropic says the control plane supplies the Anthropic API endpoint and a session-scoped OAuth token. Corporate egress proxies are supported, but alternate inference endpoints are not.
Does the feature support Zero Data Retention?
No. Anthropic lists self-hosted environments as unavailable for organizations with ZDR enabled. Exact transcript retention depends on organization settings and contract; the public documentation does not publish one universal duration for these sessions.
How many runners does a company need?
Start with peak concurrently active users, because one runner locks to one account. Add capacity for users who run multiple parallel sessions, startup latency, failures, rolling maintenance, and the isolation model. Benchmark with real repositories before setting a steady-state fleet size.
Are GitLab, Bitbucket, native Windows runners, and every Claude Code surface supported?
Not in the documented beta path. Repository checkout is documented for GitHub. Runner hosts are Linux or macOS, with a Linux-container workaround on Windows. Claude Tag, Claude Security, and Code Review do not yet route to self-hosted environments.
Final take
Anthropic has made Claude Code easier to place beside private repositories, internal services, custom toolchains, and customer-chosen compute. The developer experience stays familiar because web, mobile, desktop, routines, and terminal dispatch can all point at the same named environment.
The price of that convenience is a new shared-responsibility model.
Anthropic owns the session control plane and intelligence. The customer owns the machines on which that intelligence acts: their images, credentials, egress, filesystems, queue capacity, recovery behavior, metrics, and blast radius.
That makes the platform team the actual adopter. Team and Enterprise administrators can enable the feature, but developer infrastructure has to make it trustworthy.
The companies that get this right will not be the ones that merely run claude self-hosted-runner. They will be the ones that turn an environment ID into a well-defined execution class—with explicit residency, identity, network, provenance, recovery, and authorization boundaries.