How to run Claude Code in a dev container
To run Claude Code in a dev container, add the Claude Code Dev Container Feature to your .devcontainer/devcontainer.json, rebuild the container, and run claude in the container's terminal to sign in. From then on, every command Claude runs executes inside the container rather than on your machine, while the edits it makes to your project files appear in your local repository as you work.
A dev container is a Docker container described by a config file in your repo, so everyone on a team gets the same isolated environment. It runs on your machine or on a cloud host such as GitHub Codespaces, and an editor that supports the Dev Containers spec, such as VS Code, Codespaces, a JetBrains IDE or Cursor, connects to it. Plain editors without dev container support are not part of this workflow.
Do you need a dev container at all?
Most people do not, and I would not start here. If you are building your own projects, the Claude Code desktop app on your own machine is the easiest place to work, and the permission prompts are your safety net. A dev container earns its setup time in three cases.
- A team that wants every engineer, and Claude, working with the same tools, versions and dependencies.
- You want Claude's shell commands boxed in, away from the rest of your machine.
- You want to run long sessions with fewer prompts, and you want a hard boundary around what those sessions can touch.
If isolation is the only reason, compare it with the built-in Bash sandbox first. Claude Code sandbox explained covers what that gives you without Docker.
Step by step: add Claude Code to your dev container
- Create or update .devcontainer/devcontainer.json. Add a features block with "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}. The docs example uses the image mcr.microsoft.com/devcontainers/base:ubuntu. Swap in your own base image, or drop the image line if your file already uses a Dockerfile.
- Rebuild the container. In VS Code, open the Command Palette with Cmd+Shift+P on Mac or Ctrl+Shift+P on Windows and Linux and run Dev Containers: Rebuild Container. Codespaces, the Dev Containers CLI and JetBrains IDEs each have their own rebuild action.
- Sign in. Open a terminal in the rebuilt container, run claude and follow the prompt. With an Anthropic account you sign in through the browser. With Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, Claude Code uses your cloud credentials with no browser prompt.
The :1.0 at the end pins the feature's install script, not the Claude Code version. The feature installs the latest Claude Code, and Claude Code auto-updates inside the container by default. In VS Code and Codespaces, the feature also adds the Claude Code extension, and both the extension panel and claude in the terminal run inside the container and share the same ~/.claude configuration.
Fixes for the three things that usually go wrong
Common dev container problems and the fix from Anthropic's docs
| Problem | Why it happens | Fix |
|---|---|---|
| You have to sign in again after every rebuild | The container's home directory is thrown away on rebuild | Mount a named volume at ~/.claude and set CLAUDE_CONFIG_DIR to that path in containerEnv |
| First-launch setup repeats even with the volume | ~/.claude.json lives outside ~/.claude and gets discarded | Make sure CLAUDE_CONFIG_DIR points at the volume's mount path |
| Build stops with Failed to install Node.js and npm | The feature installs Node.js itself when the image lacks it, and that step failed | Add "ghcr.io/devcontainers/features/node:1": {} above the Claude Code feature and rebuild |
For the volume, the docs example uses a mount like source=claude-code-config,target=/home/node/.claude,type=volume for a container whose remoteUser is node. Replace /home/node with your container user's home directory. To keep each project's login separate, put ${devcontainerId} in the volume name.
Codespaces behaves the same way: ~/.claude survives stopping and starting a codespace but is cleared on rebuild. To carry your login across codespaces, store ANTHROPIC_API_KEY, or a long-lived token from claude setup-token as CLAUDE_CODE_OAUTH_TOKEN, as a Codespaces secret. Codespaces exposes secrets to the container as environment variables.
Running without permission prompts, safely
Because the container runs Claude Code as a non-root user and keeps commands inside the container, you can pass --dangerously-skip-permissions for unattended work. The CLI refuses that flag when launched as root, so check that remoteUser is a non-root account.
- Limit outbound traffic. Anthropic's reference container includes an init-firewall.sh script that only allows chosen destinations. It needs the NET_ADMIN and NET_RAW capabilities through runArgs, and it is optional.
- Consider auto mode instead. If you only want fewer prompts, auto mode has a classifier review actions before they run. Claude Code auto mode explains how it works.
- Teams can block the flag entirely by setting permissions.disableBypassPermissionsMode to "disable" in managed settings.
Claude Code permissions explained covers each permission mode, and running Claude Code unattended covers the habits that keep long sessions from going sideways.
Team settings: policy, versions and MCP servers
- Organization policy. On Linux, Claude Code reads /etc/claude-code/managed-settings.json at the highest precedence, so your Dockerfile can copy one into place. Anyone with write access to the repo can change that Dockerfile, so for policy people cannot bypass, the docs point to server-managed settings or MDM.
- Pin a version. The feature always installs the latest release. For reproducible builds, install a specific version from your Dockerfile with npm install -g @anthropic-ai/claude-code@X.Y.Z and set DISABLE_AUTOUPDATER to 1 in containerEnv.
- Telemetry. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 in containerEnv opts out of telemetry and error reporting, but it also turns off features that need feature flags, including Remote Control.
- MCP servers. Define them at project scope in a .mcp.json at the repo root, install any binaries they need in the Dockerfile, and add remote server domains to your network allowlist.
Environment variables are the main way you configure Claude Code in a container. Claude Code environment variables and the settings.json guide cover the ones worth knowing.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How do I install Claude Code in a dev container?
Add "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {} to the features block of .devcontainer/devcontainer.json, rebuild the container, then open a terminal in it, run claude and sign in.
Why does Claude Code ask me to log in after every rebuild?
The container's home directory is discarded on rebuild. Mount a named volume at ~/.claude and set CLAUDE_CONFIG_DIR to the same path in containerEnv so both your login and ~/.claude.json survive.
Does Claude Code work in GitHub Codespaces?
Yes. Codespaces supports the Dev Containers spec, so the same feature works. ~/.claude is cleared on rebuild there too, so store ANTHROPIC_API_KEY or a CLAUDE_CODE_OAUTH_TOKEN as a Codespaces secret to stay signed in.
Is it safe to use --dangerously-skip-permissions in a dev container?
It is safer than on your host, not fully safe. Commands stay in the container, but Claude can still edit your workspace and anything inside the container, including its credentials, can be sent out. Use trusted repos only, restrict network egress and never mount host secrets.
Does the Claude Code feature pin the Claude Code version?
No. The :1.0 tag pins the install script. The feature installs the latest Claude Code, which auto-updates. To pin a version, install it with npm in your Dockerfile and set DISABLE_AUTOUPDATER to 1.
Last reviewed by David Iya on October 22, 2026
