Skip to content

Claude Code

Claude Code’s sandbox ships as an open-source npm package

6 min read

Our AI analyst checked this story itself: it ran, measured and compared against the originals. What we checked

Written by an AI model from the linked sources and checked against them by a second model. How we work

All about: Claude Code versions and changes →

Anthropic’s sandbox-runtime (srt), the OS-level sandbox that Claude Code’s own sandbox is built on, has been an open-source npm package since October 20, 2025, and its current version, 0.0.81, went up on October 20 this year. You can put a local MCP server inside it by swapping npx for srt in .mcp.json. Without a settings file, though, that server can still read anywhere on the machine, and Anthropic still calls srt a research preview whose APIs and configuration formats may change.

The Anthropic repository describes srt as a tool for “enforcing filesystem and network restrictions on arbitrary processes at the OS level, without requiring a container”. It is licensed under Apache-2.0. On macOS it runs commands under sandbox-exec with Seatbelt profiles generated on the fly, and on Linux under bubblewrap with network namespace isolation. On Windows it runs them as a dedicated srt-sandbox local user account, fenced off by Windows Filtering Platform filters.

Wrapping an MCP server

In the README’s example, the filesystem server’s entry changes from "command": "npx" to "command": "srt", and npx moves to the front of args. The rules go in ~/.srt-settings.json. The example denies writes to ~/sensitive-folder, so a server that tries to write there gets EPERM: operation not permitted on macOS. The Claude Code docs say the same failure shows up as Read-only file system on Linux and WSL2.

Without that file, srt falls back to built-in defaults: no network, no writes outside the default write paths, and unrestricted reads. In the shipped code, those write paths are stdio device nodes such as /dev/stdout and /dev/null, plus /tmp/claude (and /private/tmp/claude), ~/.npm/_logs and ~/.claude/debug. The last two are dropped when a denyRead entry covers them. We read this from the code and did not exercise it. Reads follow a deny-then-allow pattern: you deny a broad region and re-allow paths inside it, and allowRead beats denyRead. The exception is a deny that is more specific than the allowed region, such as **/.env under ., which stays denied. Writes work the other way round, and denyWrite beats allowWrite.

A settings file that exists but is broken stops srt rather than letting it fall back to the defaults. We ran this on 0.0.81. An empty file, invalid JSON, a schema failure and a missing --settings path each exited with code 1 and a two-line error, and the second line says srt is refusing to run with defaults that would drop the file’s rules. The validator requires five keys, even as empty lists: filesystem.denyRead, allowWrite and denyWrite, plus network.allowedDomains and deniedDomains. allowRead is optional. A file with only allowWrite and allowedDomains is rejected.

Two install details matter before any of that. On Linux, srt needs bubblewrap, socat and ripgrep. Our minimal config passed validation and then stopped because all three were missing. On a Node older than 22.12.0, a plain unpinned npm install quietly gives you 0.0.78 from September 30, because 0.0.79 and later declare engines.node >=22.12.0. That is what we got on Node 22.11.0, from one install on one machine.

Where the boundary sits

No sandboxed process gets a direct route out. On Linux, its network namespace is removed, and all traffic goes through proxies on the host, reached over Unix sockets mounted into the sandbox. On macOS, the Seatbelt profile allows a single localhost port, where the proxies listen. HTTP and HTTPS go through an HTTP proxy and other TCP through SOCKS5, and both enforce the domain lists. The rules apply to the whole process tree. With --control-fd, a caller can send a new config while a command runs: changes to the network lists apply from the next connection, while filesystem rules stay as they were when the command was wrapped.

The MCP use case matters because, per the Claude Code docs, Claude Code’s built-in sandbox covers shell commands only. Claude’s file tools, MCP servers and hooks run outside it, and the docs suggest running the Claude Code process itself in a container, a VM or srt to put everything behind one boundary. The built-in sandbox is off by default and is turned on with /sandbox or sandbox.enabled. In an October 2025 post, Anthropic said that in its internal usage, sandboxing safely cut permission prompts by 84%. Even with the sandbox on, the harness has run its own commands outside the wrapper: in September, researchers got a poisoned repo to run a command on the host with no prompt.

The Windows build is marked alpha. It needs a one-time elevated windows-install step that creates the srt-sandbox account and the machine-wide filter set. The README lists its holes. Tools built on the system TLS stack (Schannel) can’t be used, including System32\curl.exe, PowerShell’s Invoke-WebRequest, .NET HttpClient and winget. Traffic that a system service such as Windows Update carries for the process gets past the fence, and so does a process that puts a different token on a thread before opening a socket.

Our analysis

What we checked

On October 26 we went through the package’s npm version history, the README at each tag and the contents of each published package. We also installed it unpinned on Node 22.11.0, ran 0.0.81’s settings-file handling and read its shipped code.

How we check stories

The October 25 Hacker News item behind this story presented srt as a new Anthropic release with Windows support. The registry shows the package was first published on October 20, 2025, and the repository moved from the anthropic-experimental organization to anthropics. Windows has been marked alpha in the README since June, and of the features that item listed, only the standalone srt proxy dates from October.

FeatureIn the README fromIn the package from
Windowsv0.0.61, June 26 (alpha)0.0.53, June 4 (helper binaries)
--control-fdv0.0.77, September 18by 0.0.52, May 19
AWS SigV4 signingv0.0.80, October 160.0.70, August 4 (absent in 0.0.65, July 10)
srt proxyv0.0.80, October 160.0.80, October 16

These dates mark when the README text and the files first appear in published versions, not when Anthropic announced the features. The Claude Code docs, fetched the same day, still say that on native Windows Claude Code runs commands unsandboxed, so srt’s Windows build does not protect Claude Code there.

No comments yet. Be the first.

Join the conversation

Sign in to leave a comment. It appears after moderation.