Run Claude Code in a Docker devcontainer

A dev container gives Claude Code an isolated, reproducible environment: commands run inside the container while edits land in your local repo. It’s also the safest place to pass --dangerously-skip-permissions, because it runs as a non-root user.

1. Add the Claude Code feature to devcontainer.json

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

What it does: saved as .devcontainer/devcontainer.json, Anthropic’s official Dev Container Feature installs the latest Claude Code (plus Node.js if missing) on build. The :1.0 tag pins the install script, not the CLI.

2. Rebuild the container

Open the VS Code Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Dev Containers: Rebuild Container. The feature also installs the VS Code extension there; other editors use their own rebuild action.

claude

What it does: open a terminal in the rebuilt container, run it, and complete the browser sign-in — no API key needed. If the callback never arrives, paste the code at the Paste code here if prompted prompt.

4. Persist auth across rebuilds

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

What it does: the home directory is wiped on rebuild, so mount a named volume at ~/.claude and set CLAUDE_CONFIG_DIR to it so ~/.claude.json lands inside. For Codespaces or CI, store ANTHROPIC_API_KEY or a CLAUDE_CODE_OAUTH_TOKEN (claude setup-token) as a secret.

5. Skip permission prompts safely in the sandbox

claude --dangerously-skip-permissions

What it does: the CLI rejects this flag as root, so keep remoteUser non-root. It drops prompts for unattended runs, but won’t stop a malicious repo from exfiltrating container data — use it only with trusted code and network egress limits. See permissions for a milder option.

Verify it worked

Run claude --version in the container; it should print a version, not “command not found”. To pin a CLI version, install it from a Dockerfile and set DISABLE_AUTOUPDATER to 1:

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

Anthropic also ships a full reference container.

If it fails:

Build stops with “Failed to install Node.js and npm”: add "ghcr.io/devcontainers/features/node:1": {} above the Claude Code feature, then rebuild.
--dangerously-skip-permissions is rejected: the container is running as root; set remoteUser to a non-root account.
Signed out after every rebuild: you skipped step 4 — mount the ~/.claude volume. For the trade-offs of unattended runs, see running Claude Code on a whole codebase safely.

Source: Development containers.