Running Claude Code in a container

What changes when the agent runs in a container

Running directly on your machine, a command has whatever your user account has: your home directory, your other repositories, your SSH keys, anything listening on localhost. Claude Code’s permission prompts, and its sandbox if you have configured one, stand between a mistaken command and all of that. They work, but prompts only work while you are still reading them.

Inside a container, the filesystem is the image plus what you mounted. Your other projects are not in there, and your dotfiles are not in there unless you put them there. Rebuilding recreates the tools and files defined by the image. It does not restore the mounted project: a bind mount is your real directory, so a deletion through it is a deletion on your disk, and no rebuild will undo it. That narrower reach is why people relax the prompts in a container. It holds for everything except the project, so commit reviewed work before commands run unattended.

What it can and cannot reach from in there

Three things decide the boundary, and only one of them is the container itself.

• The mounted repository These are your real files, so the project sits inside the boundary by design. Mount the one project, not the parent folder holding all of them.

• The network A container gets outbound network access by default. Anything your machine can route to is reachable, including services on your own network. Stopping a command from reaching an internal system takes deliberate network configuration, not just a container.

• Whatever you mount in Your SSH agent, your git credential helper, a cloud config directory. Each one is useful, and each one crosses the boundary you just built. Decide these one at a time rather than mounting your whole home directory.

Why people do it

If none of these describes you, skip the setup.

• Blast radius A bad command has far fewer of your files and services within reach, which matters most once you have started approving prompts quickly. The mounted project is still exposed, so back up anything git does not track.

• Reproducibility The image pins the language runtime, the package manager, the database client and the linters, so everyone on the team gets the same versions. Sessions stop failing on a tool that exists on one laptop and not another, and the setup instructions become the image.

• Somewhere that is not your laptop Once the environment is an image, it runs on a server or a cloud VM as easily as locally. You can leave a long task running without your machine staying awake, and you can hand the same environment to a teammate.

Secrets cross the boundary if you hand them over

Credentials you pass into a container stay fully usable in there. Hand it your real cloud credentials, an admin API token or a production database URL, and the isolation has bought you very little. A session that cannot touch your home directory but can drop a production table has not been made safer in any way that counts. Give it the narrowest credentials that do the job: a development database, a scoped token for one test project, a key you can revoke. Keep production credentials out entirely, container or not.

Running it in a container, in practice

You can use a ready-made setup or build a small image yourself. Either way the mounted project is still your real directory, so everything above about mounts and credentials still applies.

A dev container with the official feature. A dev container is a container your editor builds from a file in the repository and then works inside. Anthropic publishes a feature that installs Claude Code into one. Save this file, reopen the project in the container and start claude in the editor’s terminal. The official guide covers the rest.

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

Docker Sandboxes. Docker’s own tool for coding agents runs each one in a microVM with its own Docker daemon, filesystem and network, and keeps your credentials on the host. Install the sbx command and sign in as Docker’s documentation describes, then start it from your project:

cd path/to/your-project
sbx run claude

A plain Docker container. If you would rather build it yourself, a small image is enough:

FROM node:22-slim
RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates \
    && rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /workspace

Build it once, then start a session with the current project mounted:

docker build -t claude-code .
docker run -it --rm -v "$PWD":/workspace claude-code claude

Other sandboxing options

A container is one way to draw the boundary. These draw it differently:

• Claude Code’s built-in sandbox Run /sandbox in a session to restrict the filesystem and network access of the commands Claude Code runs, using your operating system’s own isolation instead of a container. See sandboxing in the Claude Code docs.

• Anthropic’s sandbox runtime An open-source tool that enforces filesystem and network restrictions on any process at the operating-system level, without a container, so you can wrap the whole Claude Code process. See sandbox-runtime on GitHub.

• The reference dev container Anthropic’s own example dev container adds a firewall script that limits outbound traffic to the destinations it allows, for when you want the network locked down as well. See the reference container on GitHub.

What isolation costs

File access through a bind mount can be slower than native, particularly on macOS and Windows. Test suites and watch-mode rebuilds feel it most, so time your own suite in both places before committing to the setup.

You also add a layer to debug. When something fails you have two candidates, your code or the container. Ports need publishing before you can open the app in a browser, and a service on your host that the app used to reach is suddenly at a different address.

And your machine is not in there: your aliases, your shell configuration, your logged-in CLI tools, your git identity. Installing tools into the image costs no isolation. Mounting a config directory or forwarding a credential does, so decide each one deliberately.