How to Run Claude Code in Docker Containers and Dev Environments

According to the Pragmatic Engineer Survey of 15,000 developers in early 2026, Claude Code reached a 75% adoption rate at startups and a 46% "most loved" rating across all company sizes. That popularity creates a practical problem: when Claude Code runs on a developer's host machine, it can read, write, and execute anything the developer can. One bad prompt or a malicious CLAUDE.md in a cloned repo, and you're looking at modified dotfiles, leaked SSH keys, or worse.

Containers solve this by putting Claude Code inside an isolated filesystem and network namespace. The bind-mounted project directory is the only part of your host that Claude can touch, and a firewall script can restrict outbound traffic to Anthropic's API endpoints and nothing else.

There are three paths to get there, each suited to a different workflow:

• Official dev container feature from Anthropic, installed through the Dev Containers spec. Best for teams already using VS Code, Codespaces, or JetBrains with a shared devcontainer.json.
• Docker Desktop sandboxes, launched with the sbx CLI. Best for quick isolation without editing project config files.
• Community tools like ClaudeBox, which wrap Docker Compose with pre-configured language profiles and per-project firewalls. Best for developers who want opinionated defaults and multi-project isolation out of the box.

The rest of this guide walks through setting up each one, then covers the configuration that matters regardless of which path you pick: auth persistence, network lockdown, and organization policy enforcement.

Anthropic publishes a Dev Container Feature at ghcr.io/anthropics/devcontainer-features/claude-code that installs Claude Code into any container built from the Dev Containers spec. It works with VS Code, GitHub Codespaces, JetBrains IDEs, and Cursor.

Step 1: Add the feature to devcontainer.json

Create or update .devcontainer/devcontainer.json in your repository:

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
  }
}

Replace the image line with your project's base image, or remove it if you already use a Dockerfile.

The :1.0 version tag pins the feature's install script, not the Claude Code release. The feature always installs the latest Claude Code CLI, which auto-updates itself inside the container by default.

Step 2: Rebuild the container

In VS Code, open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows/Linux) and run Dev Containers: Rebuild Container. In GitHub Codespaces, use the rebuild action from the codespace settings. For the Dev Containers CLI, run devcontainer up --workspace-folder ..

Step 3: Sign in and start coding

Open a terminal inside the rebuilt container and run claude. If you're using an Anthropic account, a browser window opens for OAuth. For Amazon Bedrock, Google Vertex AI, or Microsoft Foundry, Claude Code reads your cloud provider credentials from environment variables, with no browser prompt needed.

If the browser callback doesn't reach the container (common with port forwarding issues), copy the code shown in the browser and paste it at the terminal prompt.

That's it. Claude Code now runs inside the container, and every file edit it makes appears in your bind-mounted project directory on the host.

If you don't want to commit a devcontainer.json to your repo, Docker Desktop's sandbox feature offers a lighter-weight path. The sbx CLI launches Claude Code in a disposable container built from a pre-configured image.

Basic usage

sbx run claude ~/my-project

This mounts your project directory into the container and starts Claude Code with --dangerously-skip-permissions by default. The sandbox is disposable: stop it, and everything except your project files disappears.

Authentication Set your API key before launching:

sbx secret set -g anthropic

Or export ANTHROPIC_API_KEY in your shell. If you have a Claude subscription instead of an API key, run /login inside the Claude Code session for OAuth.

Multi-agent workflows

For parallel agent runs, Docker Desktop supports clone mode:

sbx run --clone claude -- agents

This creates isolated Git worktrees for each subagent, with results accessible through the sandbox-<name> remote. Each agent gets its own container, so they can install packages or modify config without stepping on each other.

Limitations to know

Sandboxes don't pick up user-level configuration from your host ~/.claude directory. Only project-level config in the mounted working directory is available inside the container. If you rely on global CLAUDE.md settings, user preferences, or saved MCP server configs, you'll need to recreate them inside the sandbox or switch to the full dev container approach.

Persist agent outputs across container rebuilds

A shared workspace with version history, semantic search, and MCP access for your containerized agents. Files stay organized and accessible whether the container is running or not. Start with a 14-day free trial.

Start 14-Day Trial

The official approaches assume you want one container per repository. Community tools like ClaudeBox take a different stance: one container per project, each with its own Docker image, shell history, auth state, and firewall rules.

What ClaudeBox adds

ClaudeBox (1,100+ GitHub stars as of mid-2026) wraps Docker with 15+ pre-configured development profiles. Pick a profile like "python-ml" or "rust-go" and ClaudeBox builds an image with the right compilers, package managers, and shell tools pre-installed. It also sets up Powerline Zsh with syntax highlighting, tmux integration, and GitHub CLI.

The key difference from the official dev container: ClaudeBox isolates per project rather than per repository. If you're working on three microservices that share a monorepo, you can run three separate ClaudeBox instances with different language profiles and network rules. Each instance gets its own persistent Docker image, so rebuilds only happen when you change the profile.

When to use community tools vs. the official feature

Pick the official dev container feature when:

• Your team already uses Dev Containers or Codespaces
• You want the setup checked into your repo so every contributor gets the same environment
• You need VS Code extension integration (the official feature auto-installs the Claude Code extension)

Pick ClaudeBox or similar community tools when:

• You want per-project isolation with persistent state between sessions
• You need pre-configured language stacks without writing your own Dockerfile
• You're running multiple Claude Code instances across different projects simultaneously
• You prefer Docker Compose workflows over the Dev Containers spec

Both approaches support network firewalls, non-root execution, and auth persistence. The difference is in how much setup you want to do yourself vs. how much you want the tool to decide for you.

Regardless of which container approach you use, two configuration steps matter for production workflows: keeping auth tokens alive across container rebuilds, and restricting what the container can reach over the network.

Auth persistence with named volumes

By default, rebuilding a container destroys everything in the home directory, including Claude Code's auth token stored in ~/.claude. Mount a named Docker volume at that path to keep credentials alive:

"mounts": [
  "source=claude-code-config,target=/home/node/.claude,type=volume"
]

Replace /home/node with the home directory of your container's remoteUser. To isolate state per project instead of sharing one volume across all repos, include the ${devcontainerId} variable in the source name:

"source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"

In GitHub Codespaces, ~/.claude persists across stop/start cycles but is cleared on rebuild, so the volume mount still applies. For cross-codespace auth, store ANTHROPIC_API_KEY or a token from claude setup-token as a Codespaces secret.

Network egress restriction Anthropic's reference container includes an init-firewall.sh script that blocks all outbound traffic except the domains Claude Code needs for API calls and authentication. Running this firewall inside a container requires the NET_ADMIN and NET_RAW Linux capabilities:

"runArgs": ["--cap-add=NET_ADMIN", "--cap-add=NET_RAW"]

The firewall script resolves allowed domains to IP addresses and creates iptables rules that drop everything else. This prevents a compromised session from exfiltrating data to arbitrary endpoints, even if Claude Code itself is running with --dangerously-skip-permissions.

You can customize the allowed domain list for your own needs. If your project uses MCP servers that connect to external services, add those domains to the allowlist. If you use a cloud provider like Bedrock or Vertex AI instead of Anthropic's API, swap in the appropriate endpoint domains.

Dev containers are a natural place to enforce organization-wide Claude Code settings because every developer on the team builds from the same config. Claude Code reads /etc/claude-code/managed-settings.json at the highest precedence in its settings hierarchy, overriding anything in ~/.claude or the project's .claude/ directory.

Bake settings into the image

Add a managed settings file to your Dockerfile:

RUN mkdir -p /etc/claude-code
COPY managed-settings.json /etc/claude-code/managed-settings.json

This file can restrict which tools Claude Code is allowed to use, define permission rules, configure MCP server allowlists, and set any other policy your team needs. Because it loads at the highest precedence, individual developers can't override it from their local settings.

Pin versions and disable auto-update

For reproducible builds, install a specific Claude Code version from your Dockerfile instead of using the dev container feature:

RUN npm install -g @anthropic-ai/claude-code@1.0.42

Then set the environment variable to prevent auto-updates:

"containerEnv": {
  "DISABLE_AUTOUPDATER": "1",
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
}

The second variable opts out of telemetry and error reporting, which some organizations require for compliance.

Limitations of repo-based policy

Because the Dockerfile lives in the repository, anyone with write access can change or remove the managed settings step. For policy that developers cannot bypass, deliver managed settings through Anthropic's server-managed settings or your organization's MDM (mobile device management) instead. The container-based approach is a good default, but it's defense-in-depth rather than a hard boundary.

When agents work across containers and need to share outputs, store results, or hand off files to humans, a shared workspace outside the container becomes essential. Platforms like Fast.io give agents a persistent, versioned workspace that lives independently of any single container lifecycle, with built-in search, audit logging, and consolidated MCP tools for both reads and writes.

The decision comes down to three questions: who controls the environment, how many projects run simultaneously, and whether you need the setup checked into version control.

Solo developer, single project at a time: Docker Desktop sandboxes (sbx run claude) are the fast path. No config files to maintain, no Dockerfile to write. You lose user-level settings and need to re-authenticate each session, but for quick isolation during exploratory coding, that tradeoff works.

Team with shared repos: The official dev container feature wins here. Check .devcontainer/devcontainer.json into your repository, and every contributor gets the same Claude Code environment with the same firewall rules and managed settings. Auth persistence through named volumes means developers sign in once per project.

Multi-project power user: ClaudeBox or a similar community tool gives you per-project containers with persistent state, pre-configured language stacks, and the ability to run multiple instances in parallel. The setup is heavier than a one-line sbx command, but the payoff is a fully customized environment for each project that survives between sessions.

CI/CD and automation: For unattended runs in CI pipelines, use the official dev container with --dangerously-skip-permissions and pass ANTHROPIC_API_KEY as a CI secret. Pair it with the network firewall to limit blast radius. The devcontainer CLI can build and run containers without VS Code, making it suitable for headless environments.

For teams running multiple agents that produce files, reports, or code artifacts, the container handles compute isolation while a shared workspace handles output persistence. Fast.io workspaces provide that layer: agents write to a workspace via MCP, humans review and download from the same place, and the append-only audit log tracks every action. The 14-day free trial includes full MCP access for testing the integration.