Claude Code in Docker and dev containers

The one-line dev container install

If your team already uses dev containers, this is the entire installation. The feature works with anything that supports the Dev Containers specification, including VS Code, GitHub Codespaces, JetBrains IDEs and Cursor.

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

claude

A plain image, for CI

A pipeline does not want a feature that always installs the newest release. Build the version you tested.

FROM node:22-bookworm-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
      git curl ca-certificates ripgrep less \
    && rm -rf /var/lib/apt/lists/*

ARG CLAUDE_VERSION=2.1.89
RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_VERSION}
ENV DISABLE_AUTOUPDATER=1

# An agent that can write to system paths is a worse agent, not a better one.
RUN useradd -m -s /bin/bash agent
USER agent
WORKDIR /workspace

ENTRYPOINT ["claude"]

docker build -t claude-agent .

docker run --rm -it \
  -v "$PWD:/workspace" \
  -e ANTHROPIC_API_KEY \
  claude-agent

Credentials that survive a rebuild

By default the container home directory is discarded on rebuild, so every engineer signs in again every time. The fix has two halves and skipping either one leaves you signed out.

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

• Codespaces keeps ~/.claude across stop and start, but clears it on rebuild, so the same configuration applies.
• To carry authentication across codespaces, store ANTHROPIC_API_KEY, or a CLAUDE_CODE_OAUTH_TOKEN from claude setup-token, as a Codespaces secret. Secrets appear as environment variables inside the container automatically.
• Cloud providers pass credentials through containerEnv, a Codespaces secret, or workload identity. Do not mount credential files from the host.

Restricting what the container can reach

If the agent will run code you have not read, which is the normal case the moment it installs a dependency, limit where the container can go. Start from the list of hosts Claude Code genuinely needs.

The reference dev container ships an init-firewall.sh that blocks everything outbound except the domains Claude Code and your toolchain need. Running a firewall inside a container needs extra privileges, so the reference grants NET_ADMIN and NET_RAW through runArgs. Neither the script nor those capabilities is required by Claude Code itself; if you already control egress at your own network boundary, leave them out.

The permission argument

On a laptop, approval prompts are the only thing between an agent and your filesystem, your SSH keys and your shell history. In a container with only the repository mounted and egress restricted, the blast radius is the repository and you can throw the container away.

docker run --rm -it \
  -v "$PWD:/workspace" \
  -e ANTHROPIC_API_KEY \
  claude-agent --dangerously-skip-permissions

• The CLI refuses the flag as root. Confirm remoteUser is a non-root account, or the flag simply will not run.
• Want fewer prompts without turning them off? Auto mode has a classifier review actions before they run, which is the middle setting most teams actually want.
• To forbid the flag entirely, set permissions.disableBypassPermissionsMode to "disable" in managed settings.

Policy that travels with the image

A container is a convenient place to apply policy, because the same image runs on every machine. On Linux, Claude Code reads /etc/claude-code/managed-settings.json at the highest precedence in the settings hierarchy.

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

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

Questions people ask

Keep reading