DEV Community

Cover image for Claude Code sandbox: what it is, where it runs, and how to choose one
Lookbk
Lookbk

Posted on

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 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:

  1. On Linux and WSL2, install bubblewrap and socat, and install ripgrep from your distribution's package manager. On macOS you need nothing extra.
  2. 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.
  3. Allow writes to your project directory, to ~/.claude and ~/.claude.json, and to the directory where Claude Code writes runtime files. That is /tmp on Linux and WSL2 and /private/tmp on macOS, unless you set CLAUDE_CODE_TMPDIR. On macOS, /tmp is a symlink and Seatbelt checks the resolved path.
  4. Allow the network domains the session needs: api.anthropic.com or your provider's endpoint, plus claude.ai and platform.claude.com for OAuth sign-in and token refresh. If you authenticate with an API key, you can drop those last two. On a third-party provider, keep api.anthropic.com too, because the WebFetch domain safety check still calls it unless you set skipWebFetchPreflight: true.
  5. On Linux and WSL2, write grants only apply to paths that already exist. In a fresh environment, create ~/.claude and ~/.claude.json before the first launch.
  6. Install the package globally with npm, under a prefix outside every path you allow writes to, then start Claude Code through the srt command 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.json does 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 --settings file 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-permissions or 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
Enter fullscreen mode Exit fullscreen mode

This post was drafted with AI assistance and checked against the skill's SKILL.md.

Top comments (0)