Claude Code sandbox: what it is, where it runs, and how to choose one
You want Claude Code to work through a long task without stopping to ask permission every few minutes. Once the prompts go away, the only thing limiting what a session can read, write and reach on the network is the isol
You want Claude Code to work through a long task without stopping to ask permission every few minutes. Once the prompts go away, the only thing limiting what a session can read, write and reach on the network is the isolation around it. "Claude Code sandbox" is not one feature. It is a family of isolation options, from a per-command sandbox built into Claude Code to a separate virtual machine, and you pick one based on your threat model. This article walks through the options in the official sandbox environments page.
The six options at a glance
The docs compare six approaches. The first two run on your host operating system without containers. The rest use a container or a virtual machine.
| Approach | What is isolated | Needs Docker | Setup effort |
|---|---|---|---|
| Sandboxed Bash tool | Bash, PowerShell and Monitor tool commands, plus their child processes | No | Minimal on macOS, low on Linux and WSL2 |
| Sandbox runtime | The whole Claude Code process, including file tools, MCP servers and hooks | No | Low |
| Dev container | The full development environment | Yes | Medium |
| Custom container | The full development environment | Yes | Medium to high |
| Virtual machine | The full operating system | No | High |
| Cloud sessions | By default, shell commands and file edits in a VM hosted by Anthropic | No | None, but it needs a Claude subscription |
The key split is what sits inside the boundary. The built-in Bash sandbox restricts shell commands only. The sandbox runtime and your own container or VM wrap the whole Claude Code process, so file tools, MCP servers and hooks are restricted too.
One warning from the docs applies to all of them. A sandbox reduces the impact of a breach but does not remove the risk. Anything that allows network egress can still leak data the agent can read, and anything that mounts your project writable can still change that code. Isolation also does not change what is sent to the model: your prompts and the files Claude reads go to the API either way.
Where the sandbox lives: the built-in Bash tool
The sandboxed Bash tool is part of Claude Code. It uses operating system primitives to limit filesystem and network access for the commands Claude runs. Run /sandbox to open the sandbox panel and choose a mode. It does not support native Windows, so on Windows use WSL2 or one of the container or VM approaches.
It does not cover everything in a session:
- Built-in tools such as Read, Edit and WebFetch run inside the Claude Code process. Permission rules for paths or domains gate them instead.
- MCP servers, command hooks and plugin monitors are separate processes that run unconstrained on the host.
That gap is why the Bash sandbox alone is not enough for fully unattended runs.
Sandbox runtime: one boundary around everything
The @anthropic-ai/sandbox-runtime package wraps a whole process in the same Seatbelt or bubblewrap isolation the Bash sandbox uses. The docs label it a beta research preview, so its configuration format may change.
Setup, in the order the docs give it:
- On Linux and WSL2, install
bubblewrapandsocat, and installripgrepfrom your distribution's package manager. On macOS you need nothing extra. - Write a configuration in
~/.srt-settings.json, or in a file you pass with--settings. By default the runtime denies network access and confines writes to a small set of built-in paths, so this step matters. - Allow writes to your project directory, to
~/.claudeand~/.claude.json, and to the directory where Claude Code writes runtime files. That is/tmpon Linux and WSL2 and/private/tmpon macOS, unless you setCLAUDE_CODE_TMPDIR. On macOS,/tmpis a symlink and Seatbelt checks the resolved path. - Allow the network domains the session needs:
api.anthropic.comor your provider's endpoint, plusclaude.aiandplatform.claude.comfor OAuth sign-in and token refresh. If you authenticate with an API key, you can drop those last two. On a third-party provider, keepapi.anthropic.comtoo, because the WebFetch domain safety check still calls it unless you setskipWebFetchPreflight: true. - On Linux and WSL2, write grants only apply to paths that already exist. In a fresh environment, create
~/.claudeand~/.claude.jsonbefore the first launch. - Install the package globally with npm, under a prefix outside every path you allow writes to, then start Claude Code through the
srtcommand from your project directory. The same command can sandbox standalone MCP servers and other helper processes.
What the runtime blocks without being asked
denyWrite takes precedence over allowWrite. At the project root the runtime denies .git/hooks, .mcp.json, .claude/commands, .claude/agents and shell startup files. It also denies .git/config unless you set filesystem.allowGitConfig: true.
There is a platform difference. On macOS these denies are checked at write time, so they cover nested files and repositories created during the session. On Linux and WSL2 the deny list is built once at launch. It reliably covers the project root and makes a best-effort shallow scan for nested copies, but it does not cover anything created later, such as the results of git init, git clone or scaffolding.
Common problems
-
No settings file: if
~/.srt-settings.jsondoes not exist and you pass no--settings, the runtime still starts, with network blocked and writes confined to built-in paths. A clean start does not prove your settings loaded. -
Bad settings file: if the file is empty, unreadable or invalid, the runtime refuses to start. It also refuses if the
--settingsfile does not exist. -
Other config paths: your write grants may include other places Claude Code loads configuration from. Deny those with
denyWrite. Otherwise a sandboxed session could persist hooks, permission rules or MCP servers that run unsandboxed on the next launch.
After an unattended run, review the paths you kept writable. On Linux and WSL2, also review anything the session created.
Dev containers, custom containers and VMs
A dev container runs Claude Code inside a Docker container that VS Code or a compatible editor manages, with your project mounted in. The claude-code repository publishes an example with a default-deny iptables firewall. Copy it into your repository and adjust the firewall allowlist, the base image and the pinned Claude Code version. Because the firewall blocks unapproved egress, that setup supports running with --dangerously-skip-permissions for unattended work.
A custom container is any Docker or OCI image with your own network policies, mounted volumes and seccomp profiles. The docs call it the most common path for organizations with existing container infrastructure or CI runners. The checklist is the same wherever the container is hosted: what is mounted writable, which credentials and tokens are reachable inside, and what the egress policy allows. You can layer the built-in Bash sandbox inside it, but unprivileged containers need enableWeakerNestedSandbox.
A virtual machine gives the strongest separation, with its own kernel. Choose it when policy requires kernel-level separation between the agent and the host, or when no host-level approach meets your compliance needs.
Cloud sessions run shell commands and file edits in an isolated VM managed by Anthropic, behind a network proxy with a default allowlist. A separate proxy keeps your GitHub token outside the sandbox. They require a Claude subscription, and a connected GitHub account to work in a GitHub repository.
How to choose
Match your goal to a starting point:
-
Fewer prompts during everyday work on your own machine: the sandboxed Bash tool in auto-allow mode, configured with
/sandbox. -
Unattended runs with
--dangerously-skip-permissionsor auto mode: the preconfigured dev container, any container or VM, or the sandbox runtime. - Isolating MCP servers and hooks without Docker: the sandbox runtime.
- A standard environment across a team: the example dev container, copied into your repository.
- No local setup on the device: a cloud session.
- A native Windows host: a container or VM, or the Bash sandbox inside WSL2.
Permission modes and isolation do different jobs. A mode decides whether a tool call runs and whether you are prompted. Isolation limits what the command can reach once it runs. With --dangerously-skip-permissions nothing asks you first, so run it inside a container, a VM or the sandbox runtime. Claude Code also refuses to start with that flag as root on Linux and macOS, so use a non-root user. Auto mode uses a classifier that reviews each action. That is a per-action control, not an isolation boundary, so isolation adds defense in depth but is not required the way it is for the skip-permissions flag.
For organizations, only the built-in Bash sandbox is enforced by Claude Code itself, through the sandbox keys in managed settings. A dev container is a convention, because Claude Code does not require one. For custom containers and VMs, distribute Claude Code through the approved image and use device management or software allowlisting to block installs elsewhere.
Something to try in Claude Code
Pricing Kit is a free skill from our open-source repository at https://github.com/lookbkdev/lookbk-skills: a pricing section built around one shared price scale, where every plan hangs from its real price on a ruled axis by a leader line. Flip the monthly/yearly switch and each price rolls digit by digit while its dot slides along the scale and a hatched stretch shows the money kept, with the arithmetic printed under every price. The recommended plan is a different object, not a badge, a comparison opens out of the cards, an optional usage calculator re-lights the cheapest plan and names the crossover, and it ships with two looks, folded plans on phones, reduced motion and a paste-in embed. The install guide covers the steps, and the skill page shows it in action.
npx skills add lookbkdev/lookbk-skills --skill pricing-kit
This post was drafted with AI assistance and checked against the skill's SKILL.md.
Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.