Claude Code in a devcontainer: setup, persistence and security

To run Claude Code in a devcontainer, add Anthropic's Claude Code Dev Container Feature to .devcontainer/devcontainer.json, rebuild the container and run claude in its terminal. Commands Claude runs then execute inside the container instead of on your host, while file edits still appear in your local repository.

That gives every engineer the same isolated environment, and a safer place to let Claude work with fewer prompts. This guide follows the official Development containers page in the Claude Code docs, read on 24 October 2026.

What is a devcontainer, and why run Claude Code in one?

A development container is a Docker container defined by a devcontainer.json file in your repo. An editor that supports the Dev Containers spec, such as VS Code, GitHub Codespaces, a JetBrains IDE or Cursor, connects to it. You edit files as usual, but the terminal, language servers and build tools run inside the container.

With Claude Code installed there, it "sees the same files, dependencies, and tools as the rest of your project's toolchain." In VS Code you can use the Claude Code extension panel or run claude in the integrated terminal; both run inside the container and share one ~/.claude configuration.

Anthropic is clear about the limits. The docs warn: "While the dev container provides substantial protections, no system is completely immune to all attacks." With --dangerously-skip-permissions, a malicious project could exfiltrate anything inside the container, including Claude Code credentials. Use devcontainers with trusted repositories, and avoid mounting host secrets such as ~/.ssh or cloud credential files.

How do you add Claude Code to a devcontainer?

1. Add the feature. Save this as .devcontainer/devcontainer.json, or add the features block to your existing file:

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

Swap the image line for your project's base image, or drop it if you build from a Dockerfile. The feature source is on GitHub.

The :1.0 tag pins the feature's install script, "not the Claude Code release." The feature installs the latest Claude Code, which auto-updates inside the container by default. It also installs Node.js when the base image lacks it. If that fails with Failed to install Node.js and npm, add "ghcr.io/devcontainers/features/node:1": {} above the Claude Code feature and rebuild.

2. Rebuild. In VS Code, open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows and Linux) and run Dev Containers: Rebuild Container. Codespaces and the Dev Containers CLI have their own rebuild actions.

3. Sign in. Open a terminal in the container, run claude and follow the prompt. With an Anthropic account you sign in through a browser. With Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, Claude Code uses your cloud credentials, which the docs suggest passing as environment variables through containerEnv, a Codespaces secret or workload identity rather than mounting files.

If the browser sign-in finishes but the callback never reaches the container, copy the code from the browser and paste it at the Paste code here if prompted prompt.

How do you keep your Claude Code login across rebuilds?

By default the container's home directory is thrown away on rebuild, so you sign in again every time. Claude Code keeps its auth token, settings and history in ~/.claude, and account details, personal MCP servers and project trust in a separate ~/.claude.json file.

Mount a named volume at ~/.claude and point CLAUDE_CONFIG_DIR at it, so .claude.json is written inside the volume too. This example is for a container whose remoteUser is node:

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

Replace /home/node with your remoteUser's home directory. If Claude Code still repeats first-launch setup after each rebuild, CLAUDE_CONFIG_DIR is probably missing. To keep state separate per project, put ${devcontainerId} in the volume name; the reference configuration uses source=claude-code-config-${devcontainerId}.

In GitHub Codespaces, ~/.claude survives stop and start but not a rebuild. To carry auth across codespaces, store ANTHROPIC_API_KEY or a CLAUDE_CODE_OAUTH_TOKEN from claude setup-token as a Codespaces secret.

How do you enforce team policy inside the container?

Because every engineer runs the same image, the container is a handy place for organization policy. On Linux, Claude Code reads /etc/claude-code/managed-settings.json at the highest precedence, overriding user and project settings. Copy it in from your Dockerfile:

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

The docs point out the catch: anyone with write access to the repo can change that Dockerfile step. For policy engineers cannot bypass, use server-managed settings or your MDM. The settings guide explains the precedence order.

Environment variables for every session go in containerEnv. This example from the docs turns off nonessential traffic and auto-updates:

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

Note that CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC also disables feature-flag evaluation, so features such as Remote Control won't work in that container. To pin an exact Claude Code version, skip the feature and run npm install -g @anthropic-ai/claude-code@X.Y.Z in your Dockerfile with DISABLE_AUTOUPDATER set to 1.

For MCP servers, define them at project scope in a .mcp.json file at the repo root, install any binaries local servers need in the Dockerfile, and allow remote server domains in your network rules. See the Claude Code MCP guide.

How do you restrict network access and run without prompts?

You can limit outbound traffic to the domains Claude Code needs; the network access requirements list them. Anthropic's reference container includes an init-firewall.sh script that does this, and it adds the NET_ADMIN and NET_RAW capabilities through runArgs so the firewall can run. Neither is required for Claude Code itself.

With the container in place, you can pass --dangerously-skip-permissions for unattended runs, since Claude runs as a non-root user and commands stay inside the container. Three conditions from the docs:

• The CLI rejects the flag when launched as root, so set remoteUser to a non-root account.
• Claude can still modify any file in the bind-mounted workspace, which shows up on your host.
• Pair the flag with egress restrictions so a bypassed session can only reach what you allow.

If you want fewer prompts but keep checks, the docs suggest auto mode, which has a classifier review actions first. Admins can block the bypass flag entirely by setting permissions.disableBypassPermissionsMode to "disable" in managed settings. The permissions guide covers each mode, and the sandbox guide compares the built-in Bash sandbox.

How do you try Anthropic's reference container?

The anthropics/claude-code repository includes an example devcontainer with the CLI, the egress firewall, persistent volumes and a Zsh shell. The docs describe it as "a working example rather than a maintained base image."

To try it: install VS Code and the Dev Containers extension, clone the repo, open it, click Reopen in Container, then open a terminal and run claude. To reuse it, copy the .devcontainer/ folder into your project and adjust the Dockerfile.

Bringing your skills and prompts into the container

A fresh container starts with an empty ~/.claude unless you mount one, so personal skills don't come along by default. Kipt stores your Agent Skills and prompts as Markdown in a private GitHub repo you own, and one command installs every skill into Claude Code: npx skills add https://github.com/<you>/<repo>.git --all -g. One option, which is a suggestion rather than a step from the Claude Code docs, is to run that command in the container's terminal so the container gets the same skills as your laptop.

For IDE-specific setup inside the container, see the VS Code guide or the JetBrains guide.