Omniscio

OmniscioGuidesClaude Code in Docker

Claude Code in Docker: dev containers that isolate it

A dev container is a Docker container that an editor manages, with your project mounted in. Claude Code runs inside it, so the commands Claude issues execute in the container rather than on your machine.

Anthropic publishes an example dev container you can copy. Start with its .devcontainer/ folder, or add the Dev Container Feature to one you already have.

Last checked against Anthropic's Claude Code documentation on November 18, 2026. By the Omniscio team. Updated .

The reference container Anthropic ships

The example lives in Anthropic's claude-code repository under .devcontainer/. It combines the CLI, an egress firewall, persistent volumes and a Zsh-based shell, and it runs either on your machine or on a cloud host such as GitHub Codespaces.

Use it to see how the pieces fit together before applying them to your own configuration, keeping in mind what Anthropic says it is: an example you copy and adjust, not a base image you inherit updates from.

Three files make it up. None of them is required if you only add the Claude Code feature to a dev container you already have.

FileWhat it holds
devcontainer.jsonVolume mounts, runArgs capabilities, editor extensions and containerEnv
DockerfileThe base image, development tools and the Claude Code install
init-firewall.shLimits outbound network traffic to the destinations the script allows

Source: "Try the reference container" in Development containers, read November 18, 2026.

Add Claude Code to your own dev container

The lighter route is the Claude Code Dev Container Feature. You add it to .devcontainer/devcontainer.json and rebuild, and the editor installs Claude Code inside the container for you.

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

The version tag pins the feature's install script, not the Claude Code release. The feature installs the latest Claude Code, and Claude Code keeps updating itself inside the container by default. To pin a version, install it from your Dockerfile instead.

The feature installs Node.js itself when the base image does not provide it. If that step fails, the build stops with Failed to install Node.js and npm, and Anthropic's fix is to add the Node feature above the Claude Code feature.

Source: "Add Claude Code to your dev container" in Development containers, read November 18, 2026.

What the reference container includes

Three choices do the work. The container runs Claude Code as a non-root user, because the CLI rejects the skip flag when launched as root. An egress firewall limits outbound traffic to a list of destinations. Volume mounts keep the configuration between rebuilds.

The firewall is not free. Running one inside a container needs extra permissions, so the reference adds the NET_ADMIN and NET_RAW capabilities through runArgs. Anthropic notes that neither the script nor the capabilities are required for Claude Code itself.

Configuration travels with the image too. Claude Code reads /etc/claude-code/managed-settings.json on Linux at the highest precedence, so a Dockerfile can copy a policy file into place that overrides an engineer's own settings.

Sources: "Restrict network egress" and "Enforce organization policy" in Development containers, read November 18, 2026.

Skipping permission prompts inside the container

Because the container runs Claude Code as a non-root user and confines command execution to the container, you can pass --dangerously-skip-permissions for unattended work. That is the pattern Anthropic describes, and it has a condition attached.

The condition is the firewall. Skipping prompts removes your chance to review tool calls before they run. Claude can still modify any file in the bind-mounted workspace, which appears directly on your host, and reach anything the container's network policy allows.

Anthropic's instruction is to pair the flag with egress restrictions, and its sandbox comparison page goes further: always run a --dangerously-skip-permissions session inside a container, a VM or the sandbox runtime, so file tools, MCP servers and hooks sit inside the boundary too.

There is a middle option. In auto mode a separate model reads each action before it runs and decides whether it is safe, so a team gets fewer prompts without switching the checks off; the permission modes guide covers it. Administrators can also block the flag entirely with permissions.disableBypassPermissionsMode.

Sources: "Run without permission prompts" in Development containers and "How isolation relates to permission modes" in Choose a sandbox environment, read November 18, 2026.

Credentials and what survives a rebuild

By default the container's home directory is thrown away on rebuild, so everyone signs in again each time. Claude Code keeps its token, user settings and session history under ~/.claude, and your account details and project trust in ~/.claude.json.

To keep both, mount a named volume at ~/.claude and set CLAUDE_CONFIG_DIR to the same path, so .claude.json lands on the volume as well.

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

Replace /home/node with your container user's home directory. The reference uses ${devcontainerId} in the volume name so each project gets its own state instead of sharing one volume.

Anthropic's warning about credentials is direct. Do not mount host secrets such as ~/.ssh or cloud credential files into the container; prefer repository-scoped or short-lived tokens instead.

Sources: "Persist authentication and settings across rebuilds" and the warning at the top of Development containers, read November 18, 2026.

The caveats that matter

The container is not a guarantee. Anthropic states that no system is completely immune to all attacks, and that with the skip flag a dev container does not stop a malicious project from exfiltrating anything reachable inside it, including the Claude Code credentials in ~/.claude.

Policy written into the repository is not policy. The Dockerfile lives in the repo, so anyone with write access can change or remove the managed-settings step. Anthropic's answer for policy engineers cannot edit is server-managed settings or your device management.

Isolation changes where commands run, not what leaves your machine. Prompts and the files Claude reads go to the API with or without a sandbox. The sandbox guide covers the lighter built-in option that needs no Docker at all.

A container or VM is one of the two supported paths on a native Windows host, the other being the Bash sandbox inside WSL2. The environment variables guide covers the containerEnv entries used above.

Sources: the warning and "Enforce organization policy" in Development containers, and "Compare sandboxing approaches" in Choose a sandbox environment, read November 18, 2026.

Common mistakes

  • Treating the reference as a base image. It is an example. Copy the folder and adjust the Dockerfile to your toolchain.
  • Skipping the firewall but keeping the skip flag. Without egress limits, the flag leaves the whole host network in reach of the session.
  • Leaving remoteUser as root. The CLI refuses the skip flag when launched as root, so the container will not start the way you expect.
  • Mounting a named volume without setting CLAUDE_CONFIG_DIR. .claude.json stays in the home directory and is discarded, and first-launch setup repeats.
  • Mounting ~/.ssh or cloud credentials. Anthropic says not to; use short-lived or repository-scoped tokens.

Where these answers come from

  • The reference container, the Dev Container Feature, the firewall and the skip-flag rules: Development containers, read November 18, 2026.
  • The comparison with other isolation options and the rule about the skip flag: Choose a sandbox environment, read the same day.
  • Managed settings precedence: the same page's "Enforce organization policy" section, read the same day.

Common questions

Does Claude Code need Docker to run?

No. Claude Code runs directly on your machine. Docker is only needed if you want the isolation a container gives you, and Anthropic's comparison table lists the dev container as one option among several.

Is it safe to use --dangerously-skip-permissions in a container?

Not on its own. Anthropic tells you to pair the flag with network egress restrictions, because a session can still reach anything its network policy allows and write to the bind-mounted workspace.

Why is the reference container run as a non-root user?

Because the CLI rejects --dangerously-skip-permissions when launched as root. Anthropic tells you to confirm that remoteUser in devcontainer.json is set to a non-root account.

Do I have to sign in again after every rebuild?

By default yes, because the container's home directory is discarded on rebuild. Mount a named volume at ~/.claude and set CLAUDE_CONFIG_DIR to the same path to keep the credentials and settings.