---
title: "How to run Claude Code in a Docker sandbox"
description: "Run Claude Code in a container that sees only your repo and reaches only allowed hosts. Devcontainer, docker run, Docker Sandboxes, credentials, what breaks."
url: "https://intentic.dev/guides/run-claude-code-in-a-docker-sandbox/"
updated: "2026-10-06"
---

[Guides](https://intentic.dev/guides/)

# How do you run Claude Code in a Docker sandbox?

The short answer

Run Claude Code in a container that sees only the repository you mount, holds only the credentials the task needs, and can reach only the hosts you allow. The container then becomes the boundary, which is what makes --dangerously-skip-permissions reasonable. Anthropic publishes a reference devcontainer with a default-deny firewall; Docker Sandboxes and managed workspaces package the same idea.

[Create your workspace](https://app.intentic.dev)[See the product](https://intentic.dev/features/)

## What is true regardless of what you pick

- Anthropic's docs say to run --dangerously-skip-permissions sessions only inside a container, a VM or its sandbox runtime. The CLI refuses the flag when it runs as root.
- A container does not stop exfiltration on its own. Anthropic's devcontainer docs warn that with permissions skipped, a malicious project can send out anything reachable inside the container, including Claude Code's own credentials. The network policy is what limits that.
- A bind-mounted repository is your real files. Whatever the agent deletes or rewrites in the mount is deleted or rewritten on the host, container or not.
- Claude Code keeps its sign-in in its config directory, and on Linux the credential file is ~/.claude/.credentials.json. Without a volume for that directory, and CLAUDE_CONFIG_DIR pointing at it, a container asks you to log in on every start.

## Your options, and where each one stops

| Approach | Good for | Breaks when |
| --- | --- | --- |
| **Claude Code's built-in sandbox** Turn on /sandbox and Claude's shell commands run under OS limits: writes kept to the project, network through a proxy whose allowlist starts empty. | Fewer prompts on your own laptop without Docker. Nothing to build, and it works on macOS, Linux and WSL2. | You want the whole agent contained. File tools, MCP servers and hooks run outside it, reads cover most of the machine including ~/.ssh by default, and native Windows is not supported. |
| **Anthropic's reference devcontainer** A devcontainer.json, Dockerfile and init-firewall.sh from the claude-code repository: a non-root user, a volume for Claude's config, and a default-deny firewall with a short allowlist. | VS Code or any editor that opens devcontainers, teams that want one shared definition, and a network policy you can read line by line. | You need hosts outside the allowlist, such as another package registry or your own APIs: every new source is a firewall edit. Anthropic calls it a working example, not a maintained base image. |
| **Plain docker run** Your own image with Claude Code installed, the repository bind-mounted, a named volume for the config, started by hand or from a script. | Full control with nothing to learn beyond Docker, and easy to run headless with claude -p from a script or a CI job. | You forget the parts the devcontainer gives you: a non-root user, a persisted login and network limits. By default a container can reach the whole internet. |
| **Docker Sandboxes** Docker's sbx CLI runs Claude Code in a microVM with its own kernel, Docker daemon and network, with the workspace mounted at the same path as on the host. | A stronger boundary than a container, Docker inside the sandbox, default-deny networking with presets, and credentials injected by a host-side proxy so the raw key never enters the VM. Free for local use. | Your machine is not macOS 14 on Apple silicon, Windows 11 or Ubuntu 24.04 or later, or you want several agents managed with review on top. It needs a Docker sign-in, and it is the boundary rather than the workflow. |
| **A self-hosted agent workspace** Something that runs the container for you and puts an interface on it. intentic runs a Docker sandbox on your machine, with a git worktree per agent inside it. | Several agents, runs that keep going after the terminal or browser closes, and review before changes reach your checkout, without writing the container setup yourself. | You need one agent in one repository for an afternoon, or you need default-deny egress: intentic's sandbox does not filter outbound traffic, so that policy would be yours to add. |

## What to actually do

If all you want is fewer prompts on your own laptop, turn on /sandbox first. It is built in and covers the shell, which is where most of the risk sits.

If you want to run with --dangerously-skip-permissions, use a real boundary. Anthropic's reference devcontainer is the best one to read and copy, because the firewall is a script you can audit. Docker Sandboxes gives a stronger boundary with less to maintain, on the platforms it supports.

Once there are several agents, or runs that should continue after you close the terminal, the container is only half the job. intentic runs Claude Code, Codex, Grok and others in a Docker sandbox on your machine, with a worktree per agent, credentials held inside the sandbox, and every change reviewed before it lands.

## What the container protects, and what it does not

A container turns the question of what Claude may do into what this box can reach. Inside it, prompts mostly become noise: a command approved without being read is worse than a boundary nobody has to think about.

It protects the host: files outside the mount, other projects, your SSH keys, your browser profile. It does not protect anything you put inside it. That is why three decisions matter more than the image: what you mount, which credentials go in, and where the network can go.

## Mounting the repository

Bind-mount the repository and the agent edits your real checkout, so changes show up in your editor straight away. That is the convenient default, and also why a mistake inside the container is a real mistake on the host.

The alternative is a copy inside the container, which isolates the work completely and makes getting it out a git push or a patch. Docker Sandboxes offers both: a direct mount at the same path as on the host, or a clone mode that mounts the repository read-only and gives the agent a private copy.

- Mount the repository, never your home directory.
- Run as a non-root user whose uid matches yours, or files created in the container come out owned by root.
- Keep dependency folders such as node_modules inside the container when the host is macOS or Windows: native modules built for one system do not load on the other.

## Credentials: give it a login, not your keys

Claude Code needs a credential of its own, and there are three ways to give it one. Log in inside the container, pasting the code it shows because the browser callback cannot reach the container, and keep the config directory on a volume. Generate a one-year token on the host with claude setup-token and pass it as CLAUDE_CODE_OAUTH_TOKEN, which needs a Pro, Max, Team or Enterprise plan. Or pass ANTHROPIC_API_KEY, which uses API billing instead of your plan.

Everything else the job needs should be scoped to the job: a token for one repository rather than your SSH key, a staging database rather than production. Anthropic's devcontainer docs specifically say to avoid mounting host secrets such as ~/.ssh.

## Network limits: the part most setups skip

A plain docker run has full outbound access, so an agent with skipped permissions can send anything it can read to anywhere. The fix is default-deny egress with an allowlist.

Anthropic's reference firewall does this with iptables when the container starts. It allows DNS, SSH, GitHub's published address ranges, the npm registry and the Anthropic API, rejects everything else, and checks itself by confirming that example.com is unreachable. It needs the NET_ADMIN and NET_RAW capabilities to do so. Docker Sandboxes enforces a similar policy outside the VM, with Open, Balanced and Locked Down presets.

An allowlist is only as tight as its widest entry: Docker's docs warn that its defaults include broad wildcards.

## What breaks inside the box

Most of the friction is predictable, and worth knowing before the first run rather than during it.

- Installs from a registry that is not on the allowlist. Every new dependency source is a firewall change.
- Docker inside the container. Mounting the host's Docker socket gives the agent root-level control of the host and undoes the sandbox. Use a sandbox with its own engine: Docker Sandboxes has one per sandbox, and intentic's is a capability you switch on.
- Logging in again on every start, until the config directory lives on a volume.
- Ports. A dev server inside the container is invisible until its port is published, and two containers cannot publish the same one.
- Root images. Claude Code refuses --dangerously-skip-permissions as root, so an image that defaults to root needs a user added.

## Related questions

### [Is it safe to use --dangerously-skip-permissions in Docker?](#skip-permissions-in-docker)

Safer, not safe. The container protects the host outside the mount, but Anthropic warns that a malicious project can still exfiltrate anything inside it, including Claude's own credentials, unless the network is restricted. Use it with trusted repositories, a non-root user, scoped credentials and default-deny egress.

### [Do I need a devcontainer to run Claude Code in Docker?](#need-a-devcontainer)

No. A devcontainer is a Docker setup that editors such as VS Code know how to open. A plain docker run with the repository mounted works the same way for the agent. The devcontainer earns its keep through Anthropic's reference firewall and as one shared definition for a team.

### [How do you log in to Claude Code inside a container?](#login-inside-container)

Run claude and paste the code it shows, since the browser callback cannot reach the container, and keep the config directory on a volume so the login survives restarts. For unattended runs, create a token on the host with claude setup-token and pass it in as CLAUDE_CODE_OAUTH_TOKEN.

### [What is the difference between Docker Sandboxes and a devcontainer?](#docker-sandboxes-vs-devcontainer)

A devcontainer is a container on your Docker engine, sharing the host's kernel, defined by a file in your repository. Docker Sandboxes runs each agent in a microVM with its own kernel, Docker daemon and network policy, and injects credentials from the host so raw keys never enter it. The microVM is the stronger boundary; the devcontainer is a file you can read and change.

### [Does Claude Code have a sandbox of its own?](#claude-code-built-in-sandbox)

Yes: /sandbox. It confines the shell commands Claude runs, using Seatbelt on macOS and bubblewrap on Linux and WSL2, with network access through an allowlist that starts empty. It is off by default and does not cover Claude's file tools, MCP servers or hooks, so it is a layer rather than a full boundary.

## Read next

[Credentials for agents](https://intentic.dev/guides/give-an-ai-agent-database-and-api-access-safely/)[Tools for parallel agents](https://intentic.dev/guides/best-tools-for-running-parallel-coding-agents/)[Docker setup, in the docs](https://intentic.dev/docs/docker/)[intentic vs Claude Code](https://intentic.dev/compare/claude-code/)[intentic vs Docker Sandboxes](https://intentic.dev/compare/docker-sandboxes/)

Written against the state of the field in 2026-10. This area moves fast. Spot something out of date or wrong? [Open an issue](https://github.com/intentic/intentic/issues) and it is fixed in the next build.

[Next guide Is there a self-hosted alternative to Claude Code on the web or Codex cloud? →](https://intentic.dev/guides/self-hosted-alternative-to-claude-code-on-the-web/)

[Create your workspace](https://app.intentic.dev)[All guides](https://intentic.dev/guides/)