Claude Code Sandbox and Docker: Run Agents Safely

Published 21-10-2026. Last verified 21-10-2026. Reviewed monthly because sandbox settings and advisories change between releases.

Quick answer

The Claude Code sandbox is an operating-system boundary around the shell commands Claude runs, and it covers shell commands only. This page is for a developer or tech lead who wants Claude to work with fewer permission prompts, or unattended, without giving it the run of a laptop or a CI runner. Our verdict is to turn the built-in sandbox on for everyday work, and to put the whole process in a dev container or a virtual machine before you use --dangerously-skip-permissions or leave an agent running alone. We did not run the break-out test our brief asks for, so every statement below comes from vendor documentation read on 21-10-2026 and is marked as such.

How we checked the information in this article

Our method is to read the vendor documentation, quote only what it says, date it and mark anything we did not run as not tested by us. Our gate for this page was a scripted break-out test: we only recommend a setup after trying to escape it and reporting what the script did. We did not run that test, so we recommend nothing here on the strength of our own attacks, and the capability table below is filled from documentation, not from a run.

The gate still rejected three things. We rejected the sandbox on its own as a setup for unattended runs, because the documentation says it constrains only shell commands. We rejected enableWeakerNestedSandbox as a default for containers, because the documentation says it considerably weakens security. And we rejected any start-up time figure for containers, because we measured none.

What does the built-in Claude Code sandbox do?

It restricts what Bash, PowerShell and Monitor commands can write and reach, and the operating system enforces it while the command runs. The sandbox documentation says it runs on macOS, Linux and WSL2, and that native Windows runs commands unsandboxed. On macOS it uses the built-in Seatbelt framework. On Linux and WSL2 it needs bubblewrap and socat. It is built on the open source @anthropic-ai/sandbox-runtime package.

The defaults, per the documentation: writes go to the working directory, a per-user temp directory and directories you added. Reads cover most of the machine, including ~/.ssh and ~/.aws/credentials unless you deny them. Network traffic goes through a proxy that checks each host against your allowed domains, and that list starts empty. Environment variables are inherited, secrets included. We read the credential default as the part most teams miss, so deny those paths yourself.

You turn it on with /sandbox, which offers two modes. Auto-allow runs sandboxed commands without a prompt, and regular permissions keeps the usual prompts. For a one-off session, the documentation gives claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'. Check that it works by asking Claude to run touch ~/sandbox-probe, which should fail, and curl --noproxy '*' https://example.com, which should not resolve. A command you type yourself at the ! prompt usually runs unsandboxed, so typing the probe yourself proves nothing.

One setting we would always set for shared or managed machines: sandbox.failIfUnavailable to true. By default, the documentation warns, Claude Code runs commands without sandboxing when a dependency is missing or the platform is unsupported. Our security skills collection is where we would look for guard rails around this.

What still leaks out of the sandbox?

Quite a lot, and the documentation lists it. The sandbox wraps shell commands, and these run outside it: the built-in Read, Edit, Write, WebFetch and WebSearch tools, command hooks, local MCP servers, plugin monitors, LSP servers and helper commands such as your status line command. A denyRead entry does not stop the Read tool, and allowedDomains does not limit WebFetch.

Three more gaps matter for agent work. The proxy decides from the client-supplied hostname and does not inspect TLS by default, so the documentation says code in the sandbox can potentially use domain fronting to reach hosts outside the list, and that allowing a broad domain such as github.com can open a path for data exfiltration. Claude can also ask to retry a failed command with dangerouslyDisableSandbox, and the documentation says that in bypassPermissions mode the retry runs without a prompt and that a matching allow rule such as Bash(curl *) approves it too. Setting allowUnsandboxedCommands to false turns the retry off. Finally, allowing a Unix socket such as /var/run/docker.sock effectively hands over the host.

A real bug shows why the boundary alone is not enough. The advisory for CVE-2026-39861, published 21-04-2026 and rated critical with a CVSS 3.1 score of 10,0, describes a sandbox bypass through symlinks in versions before 2.1.64. Exploiting it needed prompt injection to get malicious text into Claude's context. We have not tested it. If you want the attack side in plain terms, our guide to agentjacking and how to protect your AI coding agent covers prompt injection against coding agents. If you are worried about what a skill itself can do, read whether AI agent skills are safe and our report on the ToxicSkills and ClawHavoc agent skills security crisis.

When do you need Docker or a dev container instead?

When the agent runs unattended, or when file tools, MCP servers and hooks must sit behind the same wall as Bash. The sandbox environments page says the sandboxed Bash tool on its own is not sufficient for fully unattended runs, and that you should run --dangerously-skip-permissions sessions inside a container, a VM or the sandbox runtime. On Linux and macOS, Claude Code refuses to start with that flag as root, so the container user must be non-root.

A dev container is a Docker container that an editor such as VS Code, Codespaces or a JetBrains IDE manages, with your repository bind-mounted in. The Development Container Specification defines the devcontainer.json file and "Features", which are shareable units that add tools to the container. Anthropic publishes a Feature for Claude Code. The documentation gives this minimal file, which we have not built or run:

{

"image": "mcr.microsoft.com/devcontainers/base:ubuntu",

"features": {

`"ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}`

}

The :1.0 tag pins the Feature's install script, not the Claude Code release, and the documentation says the Feature installs the latest Claude Code, which then updates itself. To pin a version, it says to install @anthropic-ai/claude-code@X.Y.Z from your Dockerfile and set DISABLE_AUTOUPDATER to 1. For network control, the reference container in the claude-code repository ships an init-firewall.sh script and needs the NET_ADMIN and NET_RAW capabilities, which the documentation calls a working example and not a maintained base image.

The documentation is blunt about the limit: with --dangerously-skip-permissions, a dev container does not stop a malicious project from exfiltrating anything reachable inside it, including the Claude credentials in ~/.claude. So we would only use a dev container on repositories we trust, and we would not mount ~/.ssh or cloud credential files into it. Docker's own security documentation adds two points that apply here: the daemon needs root unless you use rootless mode, and a container with access to the daemon can mount the host root directory. For tooling around containers and cloud infrastructure, browse our DevOps and cloud skills.

Our pick by situation is below. This is our judgment from the documentation, ranked from least to most isolation, and the reason sits in each row.

Setup	Isolates	Host filesystem	Network	Credentials	Why it sits here
Built-in sandbox	Shell commands only	Writes limited to the working directory; reads open by default	Proxy with allowed domains, starting empty	Env vars inherited; ~/.ssh readable unless denied	First, because it is free and fast to set up, but it is the weakest boundary.
Sandbox runtime	The whole Claude Code process	Writes limited to paths you configure	Denied by default; you allow domains	Whatever you leave readable	Next, because it covers hooks and MCP servers, but the package is a beta research preview.
Dev container	Whole dev environment	Repository bind-mounted writable	Open unless you add a firewall	Whatever you mount or pass in	Third, because it is the team default, but the firewall is your job.
Virtual machine	Whole operating system, own kernel	Only what you copy in	Your policy	Only what you put in	Last, because it is the strongest and the slowest to set up.

Source: Claude Code sandbox and sandbox environments documentation, read on 21-10-2026. Not tested by us. We measured no container start-up time.

For an untrusted repository, the documentation points to a dedicated virtual machine or a cloud session. Docker Sandboxes, a microVM product from Docker, is named there as one option, and we have not used it.

How do sandbox and permission flags differ?

Permissions decide whether a tool call runs and whether you are asked first. Isolation limits what the call can reach once it runs. The documentation treats them as layers: when a permission mode lets actions run without asking, the boundary limits the damage. Our guide to Claude Code permission modes and a safer fast setup covers the permission side in more detail.

Auto mode, per the documentation, replaces the prompt with a classifier that reviews actions, and it calls that a per-action control and not an isolation boundary. So a boundary still adds depth for unattended runs, but it is required for --dangerously-skip-permissions. If you want fewer prompts with checks on, we would start with auto mode inside the sandbox. To stop engineers from using the bypass flag at all, the documentation names permissions.disableBypassPermissionsMode set to "disable" in managed settings. A tool that sets allow, deny and ask rules for agent tool calls is Agent Permission Kit, which its listing says fails closed and is free, needs Node.js 22 or later and shows no reviews yet. We have not run it. We sell skills that load into Claude, Cursor, Codex CLI and Copilot, and we name ours on this page; no vendor paid to be listed.

How do you run background agents safely?

Give each unattended session its own boundary and the least access it needs. The documentation says a background session runs in its own process and that its Bash commands are sandboxed when its settings enable it, and that subagents use the parent's sandbox configuration. Our guide to Claude Code background agents and skills covers the setup, and our agents and orchestration skills collection lists skills for running several agents.

Our rule of thumb for an unattended run has four parts: a non-root container user, an egress allowlist, no host secrets mounted, and a review of the writable paths afterwards. The sandbox runtime documentation tells you to review the paths you kept writable after an unattended run, and on Linux also anything the session created.

For the pipeline around that run, CI/CD Security Audit for GitHub Actions flags patterns such as pull_request_target with a head checkout and unpinned actions. It costs $19 on its listing, needs Node 18 or later, and its listing says it is a line-based scan, so a clean result does not mean the workflow is safe. Secret Leak Scan checks folders for leaked keys and tokens before deployment, costs $12 on its listing, and the listing says it cannot see secrets split across lines or in git history unless the files are in the working tree. For stopping an agent from declaring work done early, Claude Code Hooks: Block Done Until Tests Really Pass costs $15 until 03-11-2026 and $19 after, per the listing, and works only in Claude Code. We ran none of the four. For more checks on the code an agent produces, see our code quality and review skills and testing and debugging skills.

Where to start

Run /sandbox, pick auto-allow, set allowUnsandboxedCommands to false, deny your credential paths and run the two probe commands. If an agent will run alone, move it into a dev container or VM first. We review this page every month. This is not security or legal advice, and you should test any setup against your own threat model. Written by Samuel Rose, Founder of Agensi.

Sources

All read on 21-10-2026. The sandbox environments page is named in the text without a link because of the five-link cap.