Sandbox environments

Isolation limits what a Claude Code session can read, write and reach on the network. It matters most when you cut down permission prompts, leave Claude running unattended, or point it at a repository you do not fully trust. The options range from a lightweight wrapper around each shell command to a completely separate virtual machine.

This page compares those options, helps you match one to your situation, and explains what an organisation can actually enforce. For the security model as a whole, see Security; for Agent SDK applications, see Secure deployment.

The options side by side

The first two run directly on your host OS. The rest put Claude Code inside a container or VM.

The key distinction is in the second column. The built-in sandbox only wraps shell commands, so Claude's file tools, MCP servers and hooks still run directly on your machine. Every other option puts the whole Claude Code process inside the boundary.

Warning: Isolation limits the damage from a mistake or an attack; it does not remove risk. Anything with network egress can still leak what the agent can read, and a writable project mount can still be modified. Isolation also changes nothing about what goes to the model: prompts and files Claude reads are sent to the Anthropic API or your provider either way. See Data usage.

Which one should I use?

My own split: the Bash sandbox on my Mac for interactive work, the dev container for anything I leave running overnight, and a throwaway VM when a client hands me a repository I have never seen.

Isolation and permission modes

Permission modes decide whether an action runs and whether you are asked first. Isolation decides what that action can touch once it runs. The fewer prompts you have, the more the boundary is doing the work.

With --dangerously-skip-permissions, nothing asks you (apart from the actions no mode auto-approves), so the boundary is your only protection. Always run it inside a container, VM or the sandbox runtime so file tools, MCP servers and hooks are contained too. On Linux and macOS Claude Code refuses this flag as root, so run the environment as a non-root user.

Auto mode swaps prompts for a classifier. That is a per-action check, not a boundary, so isolation is recommended as defence in depth but not required in the way it is for bypass.

The Bash sandbox alone only constrains shell commands, which is not enough for fully unattended work in either mode. You can stack approaches: run the Bash sandbox inside a container or VM to get per-command restrictions within the outer boundary. See Sandboxing for how the sandbox interacts with rules and modes.

Built-in Bash sandbox

Built into Claude Code, using OS primitives (Seatbelt on macOS, bubblewrap on Linux and WSL2) to restrict the files and hosts that Bash, PowerShell and Monitor commands can reach. It does not run on native Windows; use WSL2 or a container there. Run /sandbox to switch it on and pick a mode, and see Sandboxing for configuring the boundary.

What it leaves uncovered:

• Built-in tools such as Read, Edit and WebFetch run inside the Claude Code process. They do not spawn arbitrary code and are governed by permission rules on paths and domains.
• MCP servers, command hooks and plugin monitors are separate processes running unconstrained on your host.

To cover those as well, wrap the entire process with the sandbox runtime, a dev container or a custom container.

Sandbox runtime

The @anthropic-ai/sandbox-runtime package applies the same Seatbelt or bubblewrap isolation to a whole process. Launch Claude Code through it and the session's tools, hooks and MCP servers are confined along with its shell commands. It is a beta research preview, so expect the configuration format to change.

Setting it up

On Linux and WSL2 you need bubblewrap and socat (see Sandboxing) plus ripgrep on your PATH, since the standalone runtime does not use Claude Code's bundled copy. macOS needs nothing extra.

Out of the box the runtime blocks the network and allows writes only to a few built-in paths, so write a config first. It goes in ~/.srt-settings.json or a file passed with --settings; the package README documents the schema.

Grant write access to:

• Your project directory.
• ~/.claude and ~/.claude.json.
• Claude Code's runtime file directory, unless you set CLAUDE_CODE_TMPDIR: /tmp on Linux and WSL2, /private/tmp on macOS (Seatbelt checks the resolved path, and /tmp is a symlink).

Allow these hosts:

• api.anthropic.com or your provider's endpoint. On a third-party provider keep api.anthropic.com as well, because the WebFetch domain safety check calls it unless skipWebFetchPreflight: true is set.
• claude.ai and platform.claude.com for OAuth sign-in and token refresh. API-key users can leave these out.

On Linux and WSL2 write grants only apply to paths that already exist, so on a fresh machine create the config paths first:

mkdir -p "$HOME/.claude"
test -f "$HOME/.claude.json" || printf '{}\n' > "$HOME/.claude.json"

Then launch:

npx @anthropic-ai/sandbox-runtime claude

The same wrapper works for standalone MCP servers or other helper processes.

What it blocks without being told

• denyWrite beats allowWrite.
• At the project root it denies .git/hooks, .git/config (unless filesystem.allowGitConfig: true), .mcp.json, .claude/commands, .claude/agents and shell startup files.
• On macOS those denies are checked at write time, so they also catch nested files and repos created mid-session.
• On Linux and WSL2 the deny list is built once at launch. It covers the project root reliably, does a best-effort shallow scan for nested copies that exist then, and misses anything created later by git init, git clone or scaffolding. The README's mandatoryDenySearchDepth section explains the scan.
• With no ~/.srt-settings.json and no --settings, it still starts, blocking the network and limiting writes to built-in paths such as /tmp/claude, ~/.npm/_logs and ~/.claude/debug. A clean start does not prove your config loaded.
• An empty, unreadable or invalid settings file, or a --settings path that does not exist, stops it starting.

Your write grants will still include other places Claude Code reads configuration from. Add those to denyWrite, otherwise a session could persist hooks, permission rules or MCP servers that run unsandboxed next time you launch normally.

After an unattended run

Review every path you left writable. On Linux and WSL2, also check anything the session created, since the deny list did not cover it.

Dev containers

A dev container runs Claude Code in a Docker container managed by VS Code or a compatible editor, with your project mounted in. You define it with a .devcontainer/ directory in your repo.

The claude-code repository publishes a reference dev container with a default-deny iptables firewall. Copy it in and adjust the firewall allowlist, base image and pinned Claude Code version. Because unapproved egress is blocked, a setup like this is suitable for --dangerously-skip-permissions.

Custom containers

Any Docker or OCI image works, with your own network policy, volumes and seccomp profile. This is the usual route for teams with existing container platforms or CI runners, and several managed sandbox services can host it for you. Whoever runs it, check three things: what is mounted writable, which credentials and tokens are reachable inside, and what egress the network policy allows.

You can layer the Bash sandbox inside. Unprivileged containers need enableWeakerNestedSandbox; see Sandboxing.

Virtual machines

A VM gives the strongest separation: its own kernel and, in cloud or microVM setups, its own virtual hardware. Options include cloud instances, local hypervisors and microVMs such as Firecracker. Choose this for evaluating untrusted code, when policy requires kernel-level separation, or when nothing host-level satisfies compliance.

Docker Sandboxes is a free, standalone Docker product (no Docker Desktop needed) that provides a microVM with its own Docker daemon and workspace sync, and can run Claude Code on any host where it is installed.

Cloud sessions

A cloud session runs in an isolated VM managed by Anthropic. A proxy enforces a default network allowlist, and a separate proxy keeps your GitHub token outside the sandbox while handing scoped credentials in for repository access. If your organisation routes sessions to a self-hosted environment, they run on your infrastructure, and isolation, egress and git credentials become your responsibility.

Use it for full VM isolation without provisioning anything, or when delegating from a device with no local setup. It needs a Claude subscription and, unless you launch from the CLI with --cloud (which can bundle and upload your local repo), a connected GitHub account.

Enforcing isolation across an organisation

Developers can opt into any of these, but enforcement differs:

• Built-in Bash sandbox: the only option Claude Code enforces itself. Deliver sandbox keys through managed settings or server-managed settings. See Sandboxing for the keys and locks.
• Dev containers: committing the reference container standardises the environment, but it is a convention, not a control, because Claude Code does not require a container. Use device management or software allowlisting if people must not run it outside.
• Custom containers and VMs: ship Claude Code in the approved image and use device management or allowlisting to stop installs elsewhere.

Related

• Sandboxing
• Dev container
• Permission modes
• Security
• Secure deployment