Claude Code's built-in Bash sandbox covers shell commands only. MCP servers, command hooks, and the built-in file tools run outside it. To put them inside a boundary, Anthropic documents the sandbox runtime, a beta package that wraps the whole Claude Code process with the same Seatbelt or bubblewrap isolation, with network denied by default.
The gap
The sandboxing documentation states that the sandbox covers shell commands and that Claude's file tools, MCP servers, and hooks run outside it. Local MCP servers, command hooks, plugin monitors, and LSP servers are separate processes that run with the host's permissions. If you let an agent use a local MCP server that can read files or reach the network, a Bash sandbox does not constrain that server at all.
That is the same gap we discuss for cloud sandbox firewalls: the controls cover the agent's shell, and the tool servers are another path.
What the sandbox runtime changes
The runtime package wraps an entire process in the same isolation the built-in sandbox uses. Running Claude Code through it constrains the session's tools, hooks, and MCP servers as well as shell commands. Anthropic labels it a beta research preview and warns the configuration format may change.
| Property | Behavior per the documentation |
|---|---|
| Default network | Denied |
| Default writes | Confined to a small set of built-in runtime paths |
| Settings file | Your configuration in a settings file you pass or a default location |
| Invalid settings | The runtime refuses to start if the file is empty, unreadable, or invalid |
| Missing default file | Starts anyway with network blocked and writes confined, so a clean start is not proof your settings loaded |
| Always denied writes | Git hooks, git config unless allowed, MCP configuration, Claude command and agent folders, shell startup files at the project root |
On macOS the denies are checked at write time, so they cover nested files created during the session. On Linux and WSL2 the deny list is built once at launch, so it reliably covers the project root and a shallow scan of existing nested copies but not things created later, such as a new clone or scaffold.
Setup steps
- Install the platform dependencies. On Linux and WSL2 that means bubblewrap and socat, plus ripgrep. On macOS no additional packages are needed.
- Write a settings file. Allow writes to your project directory, Claude Code's configuration paths, and its runtime temp directory.
- Allow network domains the session needs: the model API endpoint, and the sign-in hosts if you authenticate with an account instead of an API key.
- Create Claude Code's configuration paths before first launch on Linux and WSL2, because write grants apply only to paths that already exist.
- Launch Claude Code through the runtime with the package runner, passing the command to wrap.
- Deny writes to other locations Claude Code loads configuration from. The documentation warns that a sandboxed session able to write them could persist hooks, permission rules, or MCP servers that run unsandboxed the next time.
- After unattended runs, review the paths you kept writable, and on Linux and WSL2 review anything the session created.
A worked example: a team that needs one local MCP server
An illustrative scenario. A team wants a local MCP server that reads files in the project and searches a documentation index. They worry the server could reach beyond the project or call out.
- They run Claude Code through the sandbox runtime with network limited to the model endpoint and the documentation host.
- Writes are confined to the project directory plus the required Claude paths.
- The MCP server starts inside the wrapper, so it inherits the same limits.
- They test by asking the server to read a file in the home directory outside the project and to fetch an unlisted host. Both fail.
- They record the settings file in version control and review changes.
Because the runtime wraps the whole process, the server's reach is no wider than the agent's.
Limits to keep in mind
- Beta. The documentation calls it a research preview. Pin versions and expect change.
- Allowed network can still leak. The documentation warns that any approach allowing network egress can still leak data the agent can read.
- Writable project. A writable project directory can still be modified, so review changes.
- Model traffic. Isolation does not change what is sent to the model.
- Linux creation gap. Files created after launch are not covered by the deny list scan.
Choosing between the runtime and a container
| Factor | Sandbox runtime | Container or VM |
|---|---|---|
| Docker needed | No | Container yes, VM no |
| Setup | Low | Medium to high |
| Isolation strength | OS level process wrapping | Container namespaces or a separate kernel |
| Kernel separation | No | VM yes |
| Fit | Developer machines and quick unattended runs | Untrusted code, compliance needs |
For untrusted repositories or a requirement for kernel level separation, the documentation points to a dedicated VM or a cloud session.
Try it yourself
Click through it at your own pace, or open it full screen.
Look at how tool calls are checked before they run, which complements an OS boundary around the process.
Where Safeguard fits
Safeguard does not provide the sandbox runtime. Its MCP Guardrail controls which MCP tools agents may call, and its agent identity, policies, and gates add layers around the agent's actions.
Quick check
Does the Bash sandbox cover MCP servers?
No. The documentation says MCP servers, hooks, and built-in file tools run outside it. Use the sandbox runtime or a container to include them.
If the runtime starts, did my settings load?
Not necessarily. If the default settings file is missing, it starts anyway with network blocked. If a file exists but is invalid, it refuses to start. Test your boundary directly.
Is the sandbox runtime ready for strict compliance use?
It is documented as a beta research preview, so evaluate it with that in mind and consider a VM or container for strict requirements.
Sources
- Choose a sandbox environment (Anthropic documentation)
- Configure the sandboxed Bash tool (Anthropic documentation)
Last reviewed: 19 October 2026.
