Text of code.claude.com › docs › en › devcontainer as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Development containers - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. A development container , or dev container, lets you define an identical, isolated environment that every engineer on your team can run. With Claude Code installed in that container, commands Claude runs execute inside it rather than on the host machine, while edits to your project files appear in your local repository as you work.

This page covers installing Claude Code in a dev container , then a set of self-contained configuration topics: persisting authentication across rebuilds, enforcing organization policy, restricting network egress, and running without permission prompts. Read the ones that match your setup. While the dev container provides substantial protections, no system is completely immune to all attacks. When executed with --dangerously-skip-permissions , dev containers do not prevent a malicious project from exfiltrating anything accessible inside the container, including the Claude Code credentials stored in ~/.claude .

Only use dev containers when developing with trusted repositories, and monitor Claude’s activities. Avoid mounting host secrets such as ~/.ssh or cloud credential files into the container; prefer repository-scoped or short-lived tokens. How dev containers work with your editor A dev container runs as a Docker container, either on your machine or on a cloud host such as GitHub Codespaces. An editor that supports the Dev Containers spec, such as VS Code, GitHub Codespaces, a JetBrains IDE, or Cursor, connects to that container: you browse and edit files in the editor as usual, but the integrated terminal, language servers, and build tools all run inside the container rather than on your host.

Editors without dev container support, such as plain Vim, are not part of this workflow. Claude Code runs inside the container, so it sees the same files, dependencies, and tools as the rest of your project’s toolchain. In VS Code you can use either the Claude Code extension panel or run claude in the integrated terminal; both run inside the container and share the same ~/.claude configuration. Add Claude Code to your dev container Claude Code installs into any dev container through the Claude Code Dev Container Feature .

The settings work with any tool that supports the Dev Containers spec, such as VS Code, GitHub Codespaces, or JetBrains IDEs. The steps below use VS Code as an example. When you open the container in VS Code or Codespaces, the feature also adds the Claude Code VS Code extension; other editors ignore that part. New to dev containers? The VS Code Dev Containers tutorial walks through installing Docker, the extension, and opening your first container.

For a fuller hardened example with a firewall and persistent volumes, see Try the reference container . 1 Create or update devcontainer.json Save the following as .devcontainer/devcontainer.json in your repository, or add the features block to your existing file. The version tag at the end, such as :1.0 , pins the feature’s install script, not the Claude Code release. The feature installs the latest Claude Code, and Claude Code auto-updates itself inside the container by default.

To pin the CLI version or disable auto-update, see Enforce organization policy . .devcontainer/devcontainer.json { "image" : "mcr.microsoft.com/devcontainers/base:ubuntu" , "features" : { "ghcr.io/anthropics/devcontainer-features/claude-code:1.0" : {} } } Replace the image line with your project’s base image or remove it if your existing file uses a Dockerfile. The Claude Code feature installs Node.js itself when the base image doesn’t provide it.

If that install fails and the build stops with Failed to install Node.js and npm , add "ghcr.io/devcontainers/features/node:1": {} to the features block above the Claude Code feature and rebuild. 2 Rebuild the container Open the VS Code Command Palette with Cmd+Shift+P on Mac or Ctrl+Shift+P on Windows and Linux, and run Dev Containers: Rebuild Container . For other tools, follow that tool’s rebuild action: see rebuilding in GitHub Codespaces , the Dev Containers CLI , or your IDE’s dev container documentation.

3 Sign in to Claude Code Open a terminal in the rebuilt container and run claude , then follow the authentication prompt. What you see at the authentication prompt depends on your provider: Anthropic : sign in through a browser with your Claude or Anthropic Console account Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry : Claude Code uses your cloud provider credentials, with no browser prompt For cloud providers, pass credentials into the container as environment variables through containerEnv , a Codespaces secret, or your cloud’s workload identity rather than mounting credential files from the host.

See Amazon Bedrock , Google Cloud’s Agent Platform , or Microsoft Foundry for the credential chain Claude Code reads. See Choose your API provider to decide which path fits your organization. For the Anthropic sign-in: if no browser opens, or it signs you in and then shows a localhost connection error, use the login URL shown above the terminal’s paste prompt. Copy it into your browser, sign in there, then paste the code the browser shows into that prompt.

If pasting does nothing, see OAuth login fails in WSL2, SSH, or containers . Persist authentication and settings across rebuilds By default, the container’s home directory is discarded on rebuild, so engineers must sign in again each time. Claude Code stores its authentication token, user settings, and session history under the ~/.claude directory. It stores your account details, personal MCP servers, and per-project trust in a separate file outside that directory: ~/.claude.json .

To keep the directory and the file, mount a named volume at ~/.claude and set CLAUDE_CONFIG_DIR to the same path so Claude Code writes .claude.json inside the volume. The following example mounts the volume and sets CLAUDE_CONFIG_DIR for a container whose remoteUser is node : devcontainer.json "mounts" : [ "source=claude-code-config,target=/home/node/.claude,type=volume" ], "containerEnv" : { "CLAUDE_CONFIG_DIR" : "/home/node/.claude" } Replace /home/node with the home directory of your container’s remoteUser .

If you already set containerEnv , for example in Enforce organization policy , add CLAUDE_CONFIG_DIR to that object rather than adding a second one. If Claude Code repeats first-launch setup after each rebuild despite the mounted volume, check that containerEnv in devcontainer.json sets CLAUDE_CONFIG_DIR to the volume’s mount path. Without CLAUDE_CONFIG_DIR , ~/.claude.json stays in the home directory and is discarded on rebuild, along with its record that you completed setup.

To isolate state per project rather than sharing one volume across all repositories, include the ${devcontainerId} variable in the source name. The reference configuration uses source=claude-code-config-${devcontainerId} for this purpose. In GitHub Codespaces, ~/.claude persists when you stop and start a codespace but is cleared when you rebuild the container, so the configuration above applies there too. To carry authentication across codespaces, store ANTHROPIC_API_KEY or a CLAUDE_CODE_OAUTH_TOKEN from claude setup-token as a Codespaces secret .

Codespaces exposes secrets as environment variables inside the container automatically. Enforce organization policy A dev container is a convenient place to apply organization policy, because the same image and configuration run on every engineer’s machine. Claude Code reads /etc/claude-code/managed-settings.json on Linux and applies it at the highest precedence in the settings hierarchy , so values there override anything an engineer sets in ~/.claude or the project’s .claude/ directory.

Copy the file in

The rest of this page is on the live site.