Run Claude Code Safely in a Devcontainer

Want to run Claude Code safely without handing it your whole computer? A Claude Code devcontainer is the usual answer. It puts Claude inside a sealed, repeatable workspace, so the commands it runs stay in that workspace.

In this guide you will add Claude Code to a dev container, keep your login between rebuilds, apply team policy, limit network access and decide when it is fine to skip permission prompts.

This is Part 9 of 10 in our Advanced Claude Code series, part of our Claude Code tutorials. Last time we covered usage and costs.

Tested with Claude Code v2.1.312 on October 31, 2026. This guide follows Anthropic’s official dev container documentation, shown with highlighted screenshots of the docs pages. The Windows and Linux steps follow Anthropic’s official instructions too.

Quick Summary: Claude Code in a Dev Container

A dev container does not make Claude Code harmless. It moves where commands run, and you still decide what the container can reach.

Question	Short answer
What do you add?	The Claude Code Dev Container Feature in `.devcontainer/devcontainer.json`
Where do commands run?	Inside the container, not on your computer
Where do edits appear?	In your local repository as you work
How do you keep your login?	Mount a volume at `~/.claude` and set `CLAUDE_CONFIG_DIR`
Where does team policy go?	`/etc/claude-code/managed-settings.json` inside the image
When is it safe to skip prompts?	Only with a non-root user, a trusted repository and network limits

Flow diagram: your computer with editor and Docker leads to a dev container where Claude Code runs, then to commands and edits inside the container, then to your repo where edits show up locally — Claude Code runs inside the container, and your project files are shared with your computer

What a Dev Container Is and Why Use One With Claude Code

A development container, or dev container, is a workspace you describe in a file. Every engineer on a team can start the same one, with the same tools and settings.

Anthropic explains that when Claude Code is installed in that container, commands Claude runs execute inside it rather than on the host machine. Edits to your project files still appear in your local repository.

That is the appeal. If Claude runs a command you did not expect, it happens in a disposable environment, not in your home folder.

The setup also works with any tool that supports the Dev Containers spec, such as VS Code, GitHub Codespaces or JetBrains IDEs. Our steps use VS Code, like the official page does.

Read the Warning Before You Start

The docs open with a clear warning. A dev container gives strong protections, but no system is immune to every attack.

When Claude runs with --dangerously-skip-permissions, a malicious project can still send out anything reachable inside the container, including the Claude Code credentials stored in ~/.claude. Anthropic says to use dev containers only with trusted repositories and to avoid mounting host secrets such as ~/.ssh or cloud credential files.

Claude Code docs page with the yellow warning box about dev containers and the dangerously-skip-permissions flag highlighted in red — The warning in Anthropic’s docs: trusted repositories only, and keep host secrets out

Step 1: Add Claude Code to Your Dev Container

Claude Code installs into any dev container through the Claude Code Dev Container Feature. You only need a small block in one file.

Create or Update devcontainer.json

Save the following as .devcontainer/devcontainer.json in your repository. If you already have the file, add only the features block.

{
  "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. Remove it if your existing file uses a Dockerfile instead.

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 updates itself inside the container by default.

Claude Code docs showing the devcontainer.json example with the Claude Code feature block highlighted in red — The whole install is one feature entry in devcontainer.json

The feature installs Node.js itself when the base image does not have it. If 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.

Rebuild the Container

In VS Code, open the Command Palette with Cmd+Shift+P on Mac or Ctrl+Shift+P on Windows and Linux. Then run Dev Containers: Rebuild Container.

Other tools have their own rebuild action. GitHub Codespaces, the Dev Containers CLI and JetBrains IDEs each document it. In VS Code the feature also adds the Claude Code VS Code extension, and other editors ignore that part.

Sign In to Claude Code

Open a terminal in the rebuilt container, run claude and follow the prompt. What you see depends on your provider.

Anthropic: you 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 workload identity. Do not mount credential files from your computer.

If no browser opens, or it signs you in and then shows a localhost connection error, use the login URL shown above the paste prompt. Copy it into your own browser, sign in, then paste the code the browser shows. Our guide on login problems covers more cases.

Step 2: Keep Your Login When the Container Rebuilds

By default the container’s home directory is thrown away on every rebuild. That means you sign in again each time.

Claude Code keeps its token, settings and session history under ~/.claude. It keeps account details, personal MCP servers and per-project trust in a separate file, ~/.claude.json, outside that folder.

To keep both, mount a named volume at ~/.claude and point CLAUDE_CONFIG_DIR at the same path. 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"
}

Claude Code docs showing the mounts and containerEnv example with CLAUDE_CONFIG_DIR highlighted in red — A named volume plus CLAUDE_CONFIG_DIR keeps your login across rebuilds

Replace /home/node with the home folder of your own remoteUser. If you already have a containerEnv block, add the variable there instead of creating a second block.

If Setup Repeats After Every Rebuild

Check that containerEnv sets CLAUDE_CONFIG_DIR to the volume’s mount path. Without it, ~/.claude.json stays in the home folder and is discarded, along with the record that you finished setup.

To keep state separate per project, add the ${devcontainerId} variable to the volume’s source name. Anthropic’s reference container uses claude-code-config-${devcontainerId} for this.

Using GitHub Codespaces

In Codespaces, ~/.claude survives stopping and starting a codespace but is cleared on a rebuild. The volume setup above applies there too.

To carry your login across codespaces, store ANTHROPIC_API_KEY, or a CLAUDE_CODE_OAUTH_TOKEN from claude setup-token, as a Codespaces secret. Codespaces passes secrets into the container as environment variables.

Step 3: Enforce Team Policy Inside the Container

A dev container is a handy place for team rules, because the same image runs on every machine. Claude Code reads /etc/claude-code/managed-settings.json on Linux and gives it the highest precedence. Values there override anything set in ~/.claude or the project’s .claude/ folder.

Copy the file into place from your Dockerfile.

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

Claude Code docs showing the Dockerfile lines that copy managed-settings.json into /etc/claude-code, highlighted in red — Managed settings baked into the image take precedence over personal settings

There is a catch. The Dockerfile lives in your repository, so anyone with write access can change or remove that step.

For policy people cannot bypass by editing repository files, Anthropic points to server-managed settings or your MDM tool. Our settings files guide explains the layers.

Set Environment Variables for Every Session

Put variables in containerEnv so they apply to every Claude Code session in the container. This example turns off telemetry and error reporting and stops auto-updates.

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

One side effect to know about: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC also turns off the feature-flag checks that Remote Control and similar features need. Sessions in that container cannot use them. See our list of useful environment variables for others.

Pin a Specific Claude Code Version

The Dev Container Feature always installs the latest release. For reproducible builds, install from your Dockerfile with npm install -g @anthropic-ai/[email protected] instead of using the feature. Then set DISABLE_AUTOUPDATER to 1 in containerEnv.

Share MCP Servers With Your Team

Define MCP servers at project scope in a .mcp.json file at the repository root. That keeps them checked in beside your dev container files.

Install any programs that local stdio servers need in your Dockerfile, and add remote server domains to your network allowlist. Our MCP guide covers the basics.

Step 4: Limit What the Container Can Reach on the Network

You can restrict outbound traffic to only the domains Claude Code needs. Anthropic documents the inference and authentication domains on its network access requirements page. It documents the optional telemetry connections on a separate telemetry page.

The reference container includes a script called init-firewall.sh that allows only the destinations it lists. A firewall inside a container needs extra permissions, so the reference adds the NET_ADMIN and NET_RAW capabilities through runArgs.

Neither the script nor those capabilities are required for Claude Code itself. You can leave them out and use your own network controls instead.

Step 5: Decide About Skipping Permission Prompts

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 this flag when launched as root, so confirm remoteUser is a non-root account.

Claude Code docs section titled Run without permission prompts, highlighted in red — Anthropic’s section on running without permission prompts

Skipping prompts removes your chance to review tool calls. Claude can still change any file in the bind-mounted workspace, which shows up directly on your computer. It can also reach anything the container’s network allows.

That is why Anthropic suggests pairing the flag with the network limits from Step 4. If you only want fewer prompts, auto mode has a classifier review actions first. To block the flag entirely, set permissions.disableBypassPermissionsMode to "disable" in managed settings.

Ladder diagram from safest to riskiest: default prompts, auto mode, skip permissions with network limits, and skip permissions with an open network, which is marked avoid this — Move down the ladder only when the safeguards above it are in place

Try Anthropic’s Reference Container

The anthropics/claude-code repository includes an example dev container. It combines the CLI, the egress firewall, persistent volumes and a Zsh-based shell. Anthropic calls it a working example, not a maintained base image.

Install VS Code and the Dev Containers extension.
Clone the Claude Code repository and open it in VS Code.
Click Reopen in Container, or run Dev Containers: Reopen in Container.
When the build finishes, open a terminal with Ctrl+` and run claude.

The reference setup has three files. None is required when you use the feature in your own container, but they show one way to fit the pieces together.

File	Purpose
`devcontainer.json`	Volume mounts, `runArgs` capabilities, VS Code extensions and `containerEnv`
`Dockerfile`	Base image, development tools and the Claude Code install
`init-firewall.sh`	Limits outbound network traffic to the destinations the script allows

Claude Code docs section Try the reference container highlighted in red — The reference container is the fastest way to see every piece working together

Try It Yourself

You can ask Claude Code to draft the configuration for you, then review it line by line. Run this in a repository you trust.

Add a .devcontainer/devcontainer.json to this project that installs the Claude Code feature,
mounts a named volume at /home/node/.claude, and sets CLAUDE_CONFIG_DIR to the same path.
Do not mount any host folders. Explain each line.

Then rebuild the container, run claude, sign in, and rebuild once more. If you are not asked to sign in the second time, your volume is working.

Common Mistakes

Skipping CLAUDE_CONFIG_DIR, so setup repeats after every rebuild.
Mounting ~/.ssh or cloud credential files into the container, which Anthropic advises against.
Using --dangerously-skip-permissions on an untrusted repository.
Running as root, where the CLI rejects the skip-permissions flag.
Treating Dockerfile-based managed settings as tamper-proof when repository writers can edit them.
Expecting the :1.0 tag to pin the Claude Code version. It pins only the install script.

Pro Tips

Use short-lived or repository-scoped tokens instead of long-lived secrets.
Put ${devcontainerId} in the volume name when projects should not share state.
Pair unattended runs with a network allowlist, not just a non-root user.
Check the container with /doctor after a rebuild.
Compare options in our sandbox guide before choosing.
Browse Anthropic’s sandbox environments page to compare dev containers with VMs.

Dev Container Cheat Sheet

Cheat sheet card listing the dev container install steps and the settings for keeping login and locking down Claude Code — The settings from this guide on one card

Frequently Asked Questions

Is Claude Code safe inside a dev container?

It is safer than running on your computer, but not risk-free. Anthropic warns that with the skip-permissions flag, a malicious project can still send out anything reachable in the container, including your Claude Code credentials. Use trusted repositories only.

Do I need Docker?

Dev containers usually run on Docker, and the VS Code tutorial Anthropic links walks through installing it. GitHub Codespaces runs the container for you in the cloud.

Why do I have to sign in after every rebuild?

The home directory is discarded on rebuild. Mount a volume at ~/.claude and set CLAUDE_CONFIG_DIR to the same path to keep your login.

Does the feature install the latest Claude Code?

Yes, and Claude Code then auto-updates itself. To pin a version, install it from your Dockerfile and set DISABLE_AUTOUPDATER to 1.

Can I use Claude Code from an editor other than VS Code?

Yes. The settings work with any tool that supports the Dev Containers spec, including GitHub Codespaces and JetBrains IDEs. Only the VS Code extension part is ignored by other editors.

Conclusion

A Claude Code devcontainer gives you a repeatable, isolated place to work. Add the feature, mount a volume to keep your login, bake team policy into the image and add network limits before you ever skip a permission prompt. Use trusted repositories, keep host secrets out of the container, and explore more in our Claude AI overview.

Previous in the series: Part 8: Monitor Claude Code Usage and Costs

Next in the series: Part 10, Use Claude Code With Amazon Bedrock, Google Vertex or Microsoft Foundry, is coming soon.