# Run Claude Code in a Docker devcontainer

> Add Anthropic's official dev container feature to .devcontainer/devcontainer.json, rebuild, and run claude inside an isolated, reproducible container.

- Canonical: https://guides-ai.com/guides/claude-code-docker-devcontainer/
- Plate 04.07 · Topic: Workflows (https://guides-ai.com/topics/workflow/)
- Published: 21 Oct 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.com/

A [dev container](https://containers.dev/) 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

```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](/guides/claude-code-vscode-extension/) there; other editors use their own
rebuild action.

## 3. Sign in to Claude Code inside the container

```bash
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

```json
"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

```bash
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](/guides/claude-code-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`:

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

Anthropic also ships a full
[reference container](https://github.com/anthropics/claude-code/tree/main/.devcontainer).

**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](/guides/claude-code-whole-codebase-safely/).

Source: [Development containers](https://code.claude.com/docs/en/devcontainer).