Get the free coreGet core

Claude Code devcontainer: the config file, the setup steps and its limits

Updated 6 min readSection 02 / Sandboxing
SHORT ANSWER

A Claude Code devcontainer is a container your editor opens your project in, with Claude Code installed inside it. You need one small config file, saved as .devcontainer/devcontainer.json, and then you click Reopen in Container in VS Code. Commands Claude runs execute in the container, not on your Mac, while edits to project files appear in your local repo. With the no-prompt flag on, it still cannot stop a malicious project from sending out what is inside it.

This page gives you the config file, the steps and the limits. It suits you if you already use VS Code on a Mac and want the agent kept away from the rest of your files. If you would rather start a bare container yourself, see Claude Code in Docker.

01What a dev container is

A development container, or dev container, lets you use a container as a full-featured development environment. A container is a lightweight isolated environment for running programs. Dev containers can run locally or remotely, in a private or public cloud.

In VS Code, the Dev Containers extension opens a folder inside a container, and a devcontainer.json file tells VS Code how to create that environment. Your code stays in a folder that the Mac and the container both see, called a bind mount. The tools, and the commands Claude runs, work inside it. Your Mac stays outside.

02The minimal Claude Code devcontainer config

Save the following as .devcontainer/devcontainer.json in your repository, 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": {}
  }
}

The image line is the base system. Replace it with your project's base image, or remove it if your existing file uses a Dockerfile. The features block adds Claude Code. A Dev Container Feature is a packaged add-on that a dev container installs. The version tag at the end, :1.0, pins the feature's install script, not the Claude Code release.

03Open the project in the container

  1. Install Docker Desktop. For running containers locally on macOS, VS Code lists Docker Desktop 2.0 or later.
  2. Install VS Code and the Dev Containers extension.
  3. Save the config file from the section above in your repository and open the folder in VS Code.
  4. Reopen in the container. When prompted, click Reopen in Container, or run Dev Containers: Reopen in Container from the Command Palette.
  5. Start Claude Code in the VS Code terminal. You are now inside the container. For unattended work, Anthropic's docs say you can pass the no-prompt flag here:
claude --dangerously-skip-permissions

Pair that flag with limits on outbound traffic. Then a bypassed session can reach less. The minimal file above has no firewall. The reference container below does.

04Anthropic's reference container

Anthropic publishes a reference container in the .devcontainer folder of the anthropics/claude-code repository. It combines the CLI, an outbound firewall, persistent volumes and a Zsh-based shell. To try it, clone the Claude Code repository, open it in VS Code, and choose Reopen in Container. Three pieces matter.

A non-root user. The container runs Claude Code as a non-root user, meaning an account without administrator rights, and confines command execution to the container. The CLI rejects the no-prompt flag when launched as root. So confirm that remoteUser is a non-root account. That setting names the account your editor works as.

A firewall script. The reference has an init-firewall.sh script that limits outbound traffic to the destinations the script allows. Outbound traffic means connections that leave the container. Open the script and read which destinations it allows, because a firewall that allows too much protects too little. If you need a different list, edit the script before you build.

Extra permissions for that firewall. Running a firewall inside a container requires extra permissions, so the reference adds NET_ADMIN and NET_RAW through runArgs, the start options in the config file. In plain words, they let the container manage its own network rules. Claude Code itself does not need them or the firewall script.

The reference files are devcontainer.json, a Dockerfile and init-firewall.sh. Anthropic provides them as a working example rather than a maintained base image, so read the files and decide what you keep.

05What the Claude Code devcontainer does not stop

The docs are direct about it: while the dev container provides substantial protections, no system is completely immune to all attacks.

The sharpest point is this one. When Claude Code runs with --dangerously-skip-permissions, a dev container does not prevent a malicious project from exfiltrating anything accessible inside the container, including the Claude Code credentials stored in ~/.claude. Exfiltration means sending data out without your say-so.

Two more limits follow from the shared folder. Claude can still modify any file in the bind-mounted workspace, and the changes appear directly on your host. It can also reach anything the network policy of the dev container allows. Git is your safety net here: keep your work committed, and use git restore to bring paths in the working tree back from a restore source.

Two rules keep the risk down:

06Mac notes: speed and trust

Bind-mounting your local files into a container works, but VS Code notes it has some performance overhead on Windows and macOS. Expect slower file-heavy tasks on a Mac.

VS Code also has Workspace Trust, a switch that lets you decide whether a project folder may run code automatically. The Dev Containers extension has adopted it. Keep it on for repos you do not know.

If you only want to look at someone else's code, VS Code can open a repo in an isolated copy, a container volume. You can review a pull request or investigate a branch that way without touching your local work. That copy is a good first stop for an unfamiliar repo before you let an agent loose on it.

07Dev container, Docker, sandbox or VM

OptionFencesNote
Dev container with firewallThe whole Claude Code processThe reference setup on this page
Plain containerThe same idea without the editorClaude Code in Docker
Built-in sandboxShell commands onlyClaude Code sandbox

Anthropic's docs list the no-prompt mode for isolated environments like containers, VMs, or dev containers without internet access. The background is on dangerously-skip-permissions. Codex describes the same pattern with the same caveat: devcontainers give substantial protection but do not prevent every attack, and the pattern is for trusted repositories only. See Codex sandbox and the comparison in sandbox for an AI agent.

08Should you use a Claude Code devcontainer?

Use a Claude Code devcontainer when you want the no-prompt flag. Use it too when you want the agent walled off from the rest of your Mac while you stay in your editor. Keep your own keys out of it, keep the repo trusted, and keep a firewall on. If you only want fewer prompts on a Mac you trust, Claude Code permissions covers lighter options.

A container limits what a command can touch; it doesn't show what already ran. For the sessions you still run outside the container, Artificial Immunity's free, open-source core watches agent sessions and program starts on your Mac and reports what it finds.

FAQ

What is a dev container?

A development container is a container used as a full-featured development environment. Your editor opens your project inside it, and a devcontainer.json file tells VS Code how to create that environment.

How do I set up a Claude Code devcontainer?

Save a devcontainer.json with the Claude Code feature in .devcontainer/ in your repository, install VS Code and the Dev Containers extension, then click Reopen in Container.

Is the Claude Code devcontainer safe to use with the no-prompt flag?

It is the setup Anthropic's docs accept for that flag, because it runs Claude Code as a non-root user and confines commands to the container. The docs also say no system is completely immune.

Does the firewall in the reference container stop data theft?

It limits outbound traffic to the destinations its script allows. With the no-prompt flag on, a malicious project can still send out anything reachable inside the container, including the Claude credentials in ~/.claude.

Can I use Anthropic's reference container as my base image?

Treat it as a starting example. Anthropic's docs describe it as a working example rather than a maintained base image.

Why does the reference container need NET_ADMIN and NET_RAW?

They are extra permissions that let the container manage its own network rules, which its firewall needs. The firewall script and these permissions are not required for Claude Code itself.

Do I need Docker Desktop for VS Code dev containers on a Mac?

For a local setup, yes. VS Code lists Docker Desktop 2.0+ for macOS. Docker on a remote host or another Docker-compatible tool can also work, but VS Code does not officially support the other tools.

Sources

  1. Claude Code docs: development containers
  2. Claude Code reference dev container (GitHub)
  3. Claude Code docs: sandboxing
  4. Claude Code docs: permission modes
  5. VS Code docs: Dev Containers
  6. OpenAI Codex docs: approvals and security
  7. Artificial Immunity
Dev container up? Artificial Immunity watches the Mac where your agents work.Get the free core