# Claude Code Self-Hosted Environments - When to use them and how they work > A practical guide to Claude Code self-hosted environments: architecture, limits, security tradeoffs, and the rollout decisions that matter. **Author:** LAXIMA Team **Published:** 2026-08-16 **Updated:** 2026-08-16 **Reading time:** 10 min **Category:** technology **Tags:** claude code, anthropic, self-hosted environments, developer tools, enterprise ai **Canonical URL:** https://laxima.tech/blog/claude-code-self-hosted-environments-guide --- Claude Code self-hosted environments let teams run Claude Code cloud sessions on infrastructure they control, while Anthropic still handles the control plane and model inference. They fit teams that need internal network access, custom build tooling, or tighter execution control—not teams simply looking for “more privacy.” ## Key takeaways - Claude Code self-hosted environments are in public beta for Team and Enterprise organizations and are off by default, according to Anthropic’s documentation. - Self-hosting moves session execution, repository checkouts, build artifacts, and secrets onto your infrastructure, but prompts, responses, and tool results still go to `api.anthropic.com` for model inference. - A runner serves one user at a time and locks to that user after claiming its first session, so fleet sizing depends on concurrent active users, not only total sessions. - Anthropic states that self-hosted environments currently support repositories checked out from GitHub. - Zero Data Retention organizations cannot use self-hosted environments, and model inference cannot be routed through Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, or an LLM gateway. ## What is a Claude Code self-hosted environment? A Claude Code self-hosted environment is a destination you create in Claude admin settings so Claude Code cloud sessions run on machines inside your own infrastructure. It is not the same as running Claude locally in your terminal. Anthropic’s terminology matters. An **environment** is the named destination. A **runner** is the process you deploy inside your network. A **session** is one Claude Code task started by a developer. The distinction is easy to miss: terminal or IDE sessions already run on the developer’s machine. Self-hosting only changes where _cloud sessions_ execute. That includes sessions started from claude.ai, mobile and desktop apps, scheduled routines, and terminal usage with `claude --cloud`, per Anthropic’s docs. If what you need is simply access to a coding session from another device, Anthropic points developers toward Remote Control instead of self-hosted environments. That alone rules out a lot of unnecessary infrastructure work. ## How do Claude Code self-hosted environments work? The architecture is split: execution happens on your machines, while orchestration and inference stay with Anthropic. That boundary is the part many quick summaries blur. When a developer starts a cloud session and selects your environment, Anthropic places that session on the environment queue. One of your runners polls for work, claims the session, clones the selected repository, and starts a Claude Code child process on your host. The runner and session communicate outward over HTTPS to `api.anthropic.com`. Anthropic says it does not initiate inbound connections into your network. That has three immediate consequences. 1. **You keep execution close to internal systems.** Sessions can reach private services, databases, package registries, and internal Git infrastructure from inside your network boundary. 2. **You own the operating environment.** You choose the runner image, preinstalled SDKs, internal CLIs, compilers, and network paths. 3. **You do not self-host the model plane.** Model inference still uses the Anthropic API with session-scoped OAuth tokens. So self-hosting is best understood as an infrastructure control feature, not an alternative model deployment path. If your main requirement is routing inference through a different platform or gateway, Anthropic explicitly says this setup does not do that. ## When should you choose self-hosted instead of Anthropic-hosted? Choose self-hosted environments when session execution must live inside your infrastructure for network, tooling, or compliance reasons. Stay with Anthropic-hosted environments when convenience, lower operational overhead, and faster rollout matter more. A simple decision rule helps:

Requirement

Anthropic-hosted is usually enough

Self-hosted is usually better

Needs access to internal services

No

Yes

Needs preinstalled internal SDKs or CLIs

Sometimes

Yes

Wants no infrastructure to operate

Yes

No

Wants repository checkouts and artifacts on company machines

No

Yes

Needs alternative inference routing

No

No

Only wants browser-based convenience

Yes

No

A useful rule of thumb: self-host only if at least one of these is true. - Your repos or dependencies are reachable only from inside your network. - Your builds depend on internal package mirrors, private registries, or licensed binaries you cannot expose publicly. - Your security team requires checked-out code and generated artifacts to stay on company-owned infrastructure. Do _not_ self-host just because the term sounds safer. Session content still goes to Anthropic for inference. If the blocker is transcript retention policy, self-hosting is not the workaround. Teams evaluating broader Claude workflows should also read LAXIMA’s [technical guide to Claude AI and enterprise workflows](https://laxima.tech/blog/the-technical-guide-to-claude-ai-2026-models-claude-code-and-enterprise-workflows) for the bigger deployment picture. ## What stays on your infrastructure, and what does not? Execution artifacts stay with you; conversation data does not. That is the cleanest way to remember the boundary. Anthropic says repository checkouts, build artifacts, secrets, and files created or modified during a session stay on the machines you provision. At the same time, prompts, responses, and tool results go to `api.anthropic.com` for model inference, and Anthropic stores the session transcript so the session can be resumed from supported surfaces. This leads to a useful mental model: - **Data plane for code and files:** yours. - **Control plane for queueing and UI:** Anthropic’s. - **Inference plane for the model:** Anthropic’s. That three-plane model is a practical shortcut for governance reviews. It clarifies why security teams may still need approval even though the workload “runs inside our VPC.” If your organization is designing security controls around AI-generated software, LAXIMA’s guide on [production-ready AI systems and reliability](https://laxima.tech/blog/ai-generated-code-is-cheap-reliability-isnt) pairs well with this architecture review. ## What are the current limitations? The current limits are substantial enough that they should shape the rollout plan from the start. This feature is not a drop-in fit for every Claude deployment. According to Anthropic’s self-hosted environments documentation: - Self-hosted environments are in **public beta** for **Team and Enterprise** plans. - They are **off by default** and must be enabled by an owner or admin on the Cloud environments admin page. - They are **unavailable** for organizations with **Zero Data Retention** enabled. - Model inference **cannot** be routed through Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, or an LLM gateway. - Supported cloud-session surfaces include Claude Code on the web, mobile and desktop apps, scheduled routines, and terminal sessions using `claude --cloud` or environment dispatch. - Claude Tag, Claude Security, and Code Review sessions do **not** route to self-hosted environments yet. - Repositories checked out by sessions currently come from **GitHub**. - Billing works the same way as Claude Code usage in Anthropic-hosted environments. Those constraints point to a sensible rollout strategy: pilot self-hosting with one engineering group that has strong internal-network needs, not as an enterprise-wide default on day one. ## How should you size runners and capacity? Size runners around active users first, then per-user concurrency. If you size only for total task volume, you can still end up with a queue even when capacity looks fine on paper. Anthropic states that a runner locks to the first user whose session it claims and then serves only that user, up to the configured `--capacity`. That isolation helps prevent checked-out code from mixing across users, but it changes fleet math. Use this planning model: 1. **Estimate concurrent active users.** This becomes your minimum runner-count baseline. 2. **Estimate bursty sessions per active user.** This tells you whether individual runners need higher `--capacity`. 3. **Decide whether disks should be ephemeral.** Anthropic notes that with the default `--drain-grace-sec 0`, a runner exits as soon as active sessions finish, allowing an orchestrator like Kubernetes to restart it with a fresh disk. Example: if 12 developers may actively use cloud sessions at once, assume a baseline fleet of roughly 12 available runners even if many tasks are short. If each active user may run multiple concurrent sessions, capacity tuning matters inside each user lane. This is one of the biggest operational surprises in the design. It behaves less like a generic worker pool and more like a set of short-lived, user-affined execution slots. ## What network and security assumptions matter most? The key network assumption is outbound-only connectivity from your environment to Anthropic. The key security assumption is that the runner image becomes part of your trusted software supply chain. Anthropic documents these main network paths: - Runner polling and event reporting to `api.anthropic.com` over outbound HTTPS. - Optional SCM connector traffic over WebSocket. - Git operations over HTTPS or SSH to your Git host, or via Anthropic’s Git proxy. - Child session processes maintaining event streams and model inference calls outbound to `api.anthropic.com`. Corporate egress proxies are supported via standard proxy and mTLS environment variables, and Anthropic notes that proxies must not buffer session streaming responses because the stream uses server-sent events over HTTPS. For a security review, focus on four controls first: 1. **Image hardening.** Treat the runner image like CI infrastructure. Patch it, scan it, and keep dependencies minimal. 2. **Git credential design.** Prefer short-lived or per-session credentials where possible instead of broad, static repo access. 3. **Secret scope.** Keep environment secrets and runner registration material tightly limited and rotate them through your normal platform process. 4. **Outbound allowlists.** Validate that required egress hosts and protocols are explicit, not accidental. For teams comparing agentic coding stacks more broadly, LAXIMA’s [Claude Code vs Codex vs Augment comparison](https://laxima.tech/blog/the-agentic-coding-showdown-claude-code-openai-codex-and-intent-by-augment) is useful context because hosting models and execution models vary sharply across tools. ## What operational mistakes should teams avoid? The common mistakes are mostly strategic, not just technical. Most failures begin with choosing self-hosting for the wrong reason or underestimating day-two operations. ### 1\. Confusing self-hosted execution with private inference It is not private inference. Anthropic says inference still runs through its API. If your requirement is “the model never sees the prompt,” this setup does not satisfy it. ### 2\. Treating the runner like a generic CI worker The user-locking lifecycle changes the operating model. Plan around user affinity, drain behavior, and requeue semantics, not only CPU and RAM. ### 3\. Ignoring retire and shutdown behavior Anthropic documents lease refreshes through polling and notes that if a runner stops polling for about 60 seconds, the session is requeued. If your infrastructure kills hosts on a schedule, you need a retirement strategy instead of letting sessions die as apparent crashes. ### 4\. Starting with full production access Begin with one internal service, one repo class, and one developer cohort. Add internal databases or sensitive systems only after you confirm identity verification, credential scoping, and observability. ### 5\. Over-customizing the base image too early Install only what unblocks builds and tests first. Large, bespoke images slow patching, increase attack surface, and make reproducibility harder. ## What is a sensible rollout plan? A sensible rollout is narrow, testable, and reversible. Do not launch self-hosting as a broad platform migration. 1. **Pick one hard use case.** Choose a team that truly needs internal network access or custom tooling. 2. **Create a minimal runner image.** Include only the compilers, SDKs, package managers, and internal CLIs that the pilot requires. 3. **Enable one environment.** Keep naming clear so developers know when they are choosing Anthropic-hosted versus self-hosted execution. 4. **Test end to end.** Anthropic provides documentation for a CI smoke-test path before promoting an image. 5. **Measure queue time, setup friction, and failed sessions.** Even without published benchmarks, these three signals usually reveal whether the pilot is healthy. 6. **Expand by access tier.** Add more repos, more internal services, and more users only after the first cohort is stable. If your team is already building Claude-centric DevOps workflows, LAXIMA’s [Terraform skill guide for Claude Code](https://laxima.tech/blog/building-the-ultimate-terraform-skill-for-claude-code-a-devops-guide) is a practical next read for standardizing infrastructure operations around the tool. ## Should most teams use Claude Code self-hosted environments? No—most teams should start with Anthropic-hosted environments and move to self-hosting only when they hit a real network, tooling, or compliance boundary. Anthropic says as much directly: most teams are better served by Anthropic-hosted environments because they require no infrastructure to run or maintain. That recommendation is stronger than it may first appear. Self-hosting adds runner lifecycle management, image maintenance, egress policy work, Git credential engineering, and on-call responsibility. You should take on that burden only if it buys something concrete. The best use case is not “we prefer self-hosted on principle.” It is “our cloud sessions need private resources and curated tooling that cannot live in a generic hosted environment.” For ongoing Claude platform changes, keep an eye on LAXIMA’s [Claude tools feature guide](https://laxima.tech/blog/new-claude-tools-features-guide) and the [free AI Signal news feed](https://laxima.tech/blog/inside-laxima-tools-signal-blog). ## Frequently asked questions ### Can Claude Code self-hosted environments run fully offline? No. Anthropic’s documentation says runners poll api.anthropic.com for work, child sessions stream events back over HTTPS, and model inference uses the Anthropic API. Self-hosted environments remove the need for inbound connectivity into your network, but they do not support offline operation. ### Do self-hosted environments replace local Claude Code use in the terminal or IDE? No. Anthropic distinguishes self-hosted cloud sessions from local sessions. Terminal and IDE sessions already run on the developer’s own machine. Self-hosted environments are for cloud sessions launched from supported surfaces when you want those sessions to execute on infrastructure your organization controls. ### Does self-hosting reduce Claude Code billing? No. Anthropic states that sessions in a self-hosted environment consume your organization’s Claude Code usage the same way sessions in Anthropic-hosted environments do. Self-hosting changes where sessions execute, not the basic Claude Code usage model. ### Can self-hosted environments use non-GitHub repositories? Anthropic’s current self-hosted environments documentation says sessions check out repositories from GitHub. A human editor should still re-check this before publishing in case repository support expands after the current beta documentation. ### Why does runner user-locking matter so much for capacity planning? Anthropic says a runner locks to the first user whose session it claims and then serves only that user up to its configured capacity. That means capacity planning depends on how many users may be active at the same time, not just how many total sessions you expect to process.