If you work with Claude Code, you know the drill: the agent wants to run a command, the terminal pops a permission prompt; another command, another prompt. Half an hour in, you have clicked "Allow" thirty times and your finger is on autopilot. Anthropic's own telemetry puts it in numbers: users approve roughly 93% of permission prompts [official, from its engineering blog companion piece "How we contain Claude"]. An approval rate that high means the gate has stopped gating - you are rubber-stamping, or you turned prompts off long ago. Either way, the machine's keys are effectively with the model.
There is a different approach: don't give the agent root in the first place. Carve out a few precise openings at the operating-system level and wall off everything else. Anthropic's answer is a CLI that ships independently of Claude Code: sandbox-runtime. It wraps any process in filesystem and network restrictions using OS primitives - no container required. Repository: github.com/anthropics/sandbox-runtime. This article does one job: get the thing installed and running on your machine, with every platform's real-world traps spelled out. Whether your agent needs isolation at all is a separate question - see the related reading.
First, the Timeline: This Is Not "Newly Open-Sourced This Week"
A recent wave of media coverage makes it sound like a fresh open-source release. The timeline says otherwise:
- The repository's created_at is 2025-10-20 - it has been public for over a year [official, GitHub API].
- Anthropic's engineering blog post "Making Claude Code safer with sandboxing" was published in May 2026 [official].
- The recent cluster of coverage (late October 2026) is a second-hand retelling of a second-hand retelling (a MarkTechPost piece from Oct 24); "newly open-sourced" is inaccurate [secondary].
This article is an installation guide, not news coverage. Why install now? Because Claude Code's sandboxing has moved from optional experiment toward default recommendation, while most tutorials still teach the old approve-everything workflow. As measured via GitHub API on 2026-10-25 [official]: 6,615 stars, 303 open issues, TypeScript, Apache-2.0 license, latest release v0.0.81, default branch main. The README carries a status banner: Beta Research Preview, "APIs and configuration formats may evolve." Expect API churn.
What srt Is: OS Primitives, Not Containers
The README's self-description, verbatim: "A lightweight sandboxing tool for enforcing filesystem and network restrictions on arbitrary processes at the OS level, without requiring a container." [official] Three takeaways:
First, it governs "arbitrary processes." Wrap Claude Code's Bash calls, or any command-line tool you do not fully trust - the agent use case is not mandatory.
Second, it builds on OS primitives - no Docker, no microVM. Each platform has its own path [official, README]: macOS uses sandbox-exec (Seatbelt) with custom profiles and needs no extra dependencies; Linux uses bubblewrap (bwrap); Windows uses WFP (Windows Filtering Platform) as an egress fence. The engineering blog phrases it as "built on top of OS level primitives such as Linux bubblewrap and MacOS seatbelt" [official]. Community comparison tables [secondary, MarkTechPost] make the peer group explicit: Docker Sandboxes run a microVM per sandbox, E2B runs on Firecracker - both virtualization routes, while srt takes the lightest OS-primitive route.
Third, the design philosophy is secure-by-default. README, verbatim: "processes start with minimal access, and you explicitly poke only the holes you need" [official].
Installation on Three Platforms
The install command (README, verbatim):
npm install -g @anthropic-ai/sandbox-runtimeThen try it [official, README examples]:
srt "curl anthropic.com" # on the allowlist - succeeds
srt "curl example.com" # Connection blocked by network allowlistOne command through, one blocked - the network fence works. Swap in your workflow's real domains to verify the config quickly. One caveat: a secondary source [MarkTechPost] claims Node.js >=22.12+ is required, but this does not appear in the README as captured - check the repository's package.json yourself before installing.
macOS: zero extra dependencies, works right after install. The smoothest of the three paths.
Linux: needs the trio of bubblewrap, socat, and ripgrep (apt-get install bubblewrap on Ubuntu/Debian), with bwrap >=0.4.0; only "denyRead/credential masking for non-regular files" needs >=0.5.0, and older versions warn instead of refusing [official]. Ubuntu 24.04+ has one extra step: AppArmor restricts unprivileged user namespaces by default, so run:
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0bubblewrap runs without root precisely via unprivileged user namespaces - skip this sysctl on Ubuntu 24.04 and the sandbox simply will not start [official].
Windows: Alpha. The mechanism creates a dedicated srt-sandbox local user account plus a WFP egress fence (by SID) plus a write-restricted token plus explicit ACEs; a one-time admin run of npx @anthropic-ai/sandbox-runtime windows-install sets it up, with no extra dependencies afterward [official].
Windows: Three Layers of Truth, All Three Required
"Supports Windows" is the media shorthand, and it misleads on more than one level. The full picture has three layers [official, README and the Claude Code docs]:
Layer one: the srt CLI itself is Alpha on Windows. The WFP approach works, but maturity lags far behind the macOS/Linux paths.
Layer two: Schannel is a hard limit with no workaround. README, verbatim: "What does not work inside the sandbox: Schannel." Concretely, System32's bundled curl, PowerShell's Invoke-WebRequest/Invoke-RestMethod, .NET HttpClient (and therefore dotnet restore/NuGet), winget, git configured with http.sslBackend=schannel, and cargo on Windows - every tool riding the Windows Schannel TLS stack fails to complete an HTTPS handshake inside the sandbox. README again: "There is no workaround for these inside the sandbox: run such a tool outside it." Tools with their own TLS stacks (Node, Python, Go) are unaffected.
Layer three: Claude Code's sandbox does not run on native Windows at all. The official docs state: "On native Windows, Claude Code runs commands unsandboxed. To use the sandbox on a Windows machine, run Claude Code inside a WSL2 distribution." On native Windows, commands execute unsandboxed; to get sandboxing, Claude Code must run inside a WSL2 distribution. WSL1 is not supported ("Sandboxing requires WSL2"), and WSL2 uses the same bubblewrap path as Linux.
Read the three layers together: the correct path for Windows users is "WSL2 + bubblewrap," not "install a CLI on native Windows and call it done." The Schannel limitation disappears in the WSL2 scenario; on native Windows it does not.
Default Policy and ~/.srt-settings.json
srt's default policy compresses into a three-row table [official, README]:
| Dimension | Mode | Default |
|---|---|---|
| Network | allow-only | All denied; domains must be explicitly allowed. "An empty allowedDomains list means no network access" |
| Writes | allow-only | All denied; empty array = no write access; denyWrite overrides allowWrite |
| Reads | deny-then-allow | All allowed; allowRead overrides denyRead |
Note the asymmetry: network and writes are "denied by default," reads are "allowed by default." The logic is defensible - executables, system libraries, and framework source all depend on reads, so denying reads by default would stop every process from running; meanwhile network egress and file writes are the two main channels through which an agent does damage, so both are welded shut. The cost: credential files stay exposed unless you explicitly denyRead.
The config file lives at ~/.srt-settings.json by default (override with --settings). The README example, verbatim:
{
"network": {
"allowedDomains": ["github.com", "*.github.com"],
"deniedDomains": ["malicious.com"],
"allowUnixSockets": ["/var/run/docker.sock"],
"allowLocalBinding": false
},
"filesystem": {
"denyRead": ["~/.ssh"],
"allowWrite": [".", "src/", "/tmp"],
"denyWrite": [".env", "config/production.json"]
}
}Two details deserve a highlight. First, if a config file exists but is invalid, srt errors out and exits rather than silently falling back to defaults - new behavior, the result of a security fix (see pitfall #3 below). Second, be very careful with allowUnixSockets entries like docker.sock; a third-party deep-dive [secondary] relays the README's own wording that this is "effectively access to the host."
Wiring It into Claude Code: /sandbox and the Settings
Claude Code integrates this sandboxing natively. The official docs (code.claude.com/docs/en/sandboxing) give two ways to enable it [official]: run /sandbox in a session, or set sandbox.enabled to true in a settings file such as ~/.claude/settings.json. Command-line mode example (docs, verbatim):
claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'Key settings (listed in the docs):
sandbox.autoAllowBashIfSandboxed: auto-approve Bash when it runs inside the sandbox - this is the switch behind the 84% prompt reduction;sandbox.allowUnsandboxedCommands: whether commands may run outside the sandbox; keep it false;sandbox.failIfUnavailable: hard-fail when the sandbox is unavailable instead of silently falling back to unsandboxed execution; enable it;sandbox.excludedCommands: commands exempted from the sandbox;sandbox.filesystem.*andsandbox.network.*: policy semantics matching bare srt config;sandbox.credentials.files/sandbox.credentials.envVars: credential masking.
On the environment side: HTTP_PROXY/HTTPS_PROXY/ALL_PROXY inject the proxy egress; CLAUDE_CODE_SUBPROCESS_ENV_SCRUB forces filesystem isolation to persist; CLAUDE_CODE_TMPDIR controls the temp directory. Dependencies for Linux/WSL2: sudo apt-get install bubblewrap socat (dnf on Fedora).
One default-value difference you must keep straight: bare srt denies all writes by default, but the Claude Code integration's default access table is [official, docs]: writes = working directory + per-user temp directories; reads = most of the machine, including ~/.ssh and ~/.aws/credentials; network = "No direct route out," with the proxy allowlist initially empty. The integration pre-approves working-directory writes, and its default read surface is far wider than bare srt's. If you want stricter credentials hygiene, close the gap explicitly with sandbox.filesystem.denyRead and sandbox.credentials.files.
About the 84% figure: the engineering blog states, "In our internal usage, we've found that sandboxing safely reduces permission prompts by 84%." [official] The caveat: this is Anthropic's internal usage data, self-reported, with no external evaluation and no published methodology [official self-report]; MarkTechPost [secondary] likewise flags it as "self-reported number, not an external benchmark." Read it as evidence the direction works, not a prediction that your prompts will drop by exactly 84%. Background figure: telemetry shows users approve roughly 93% of prompts [official] - approval fatigue is real, and it is the product logic behind auto-approving sandboxed commands.
Pitfall List: Straight from the Issues
All items below come from the repository's issue tracker [official, captured 2026-10-25], ranked by heat:
- #139 "dotfiles leak" (opened 2026-02-18, 34 comments, the hottest in the repo): running commands and being SIGKILLed both leak dotfiles and directories. Related: #85 (closed), #171 (cannot mkdir inside an allowRead directory on Linux).
- #160 "can read envs/args of other processes" (opened 2026-03-02): with the sandbox enabled, environment variables and arguments of other processes remain readable - if credentials live in env vars, the exposure surface is larger than you think.
- #122 "config fallback silently disables filesystem read restrictions": older versions silently fell back on invalid config, disabling read restrictions in the process; fixed by PR #124, and today's "error out on invalid config" README behavior is that fix.
- Ubuntu 24.04+ AppArmor restriction: without unprivileged user namespaces, bubblewrap will not start; the sysctl above is the fix. Inside containers without CAP_SYS_ADMIN, seccomp fails with EPERM (#417).
- Per-platform network mechanics differ: Linux uses Unix socket bind-mounts, macOS Seatbelt allows exactly one localhost port, Windows uses the WFP fence [official]. "All traffic is forced through the host proxy" is a simplification that hides real implementation differences.
- "Forced through the proxy" is not fully accurate: tools that ignore proxy env vars (ssh, most database drivers) are not proxied - they simply cannot connect at all; QUIC/UDP/ICMP (including ping) cannot get out.
- Documented incompatibilities:
watchman,docker; on macOS, git over SSH fails and Go-based CLIs (gh/gcloud/terraform) may fail TLS. - Two reminders from independent analysis [secondary, ai.thesatyajit.com, author ran a Linux end-to-end]:
enableWeakerNestedSandbox"considerably weakens security," and if srt is installed inside the project directory, in-sandbox processes may be able to rewrite it - prefer a global install.
FAQ
Q1: Does running it require root or admin rights?
A1: Not for daily operation. bubblewrap on Linux runs via unprivileged user namespaces, root-free; the only exception is a one-time sysctl adjustment on Ubuntu 24.04+ (needs sudo). On Windows, windows-install creates the srt-sandbox account and WFP fence with a one-time admin elevation; afterward, no admin needed.
Q2: I already run my agent in Docker - do I still need srt?
A2: Different jobs. A container gives namespace-level isolation on a shared kernel - good against "the code trashed the environment," weaker against "the code actively escalates." srt adds process-level, fine-grained permission control, and the two can stack. One caution: allowing docker.sock via allowUnixSockets effectively hands over the host [secondary relaying official wording], so mixing them demands extra config care. The full selection picture is in the related reading.
Q3: Does it actually work on Windows? A3: Answer in three layers. The srt CLI itself: Alpha, usable, but Schannel-based tools (System32 curl, IWR, NuGet, winget, git with the schannel backend) cannot complete HTTPS handshakes inside the sandbox, with no workaround. The Claude Code sandbox: does not run on native Windows at all (unsandboxed fallback); you must use WSL2, and WSL1 is unsupported. The correct Windows path is WSL2 + bubblewrap.
Q4: Can I trust the 84% prompt-reduction figure? A4: It is a direct quote from Anthropic's engineering blog, but it is internal usage data, self-reported, with no external evaluation and no methodology details. Treat it as an official endorsement that the direction works, not a forecast for your workload. For context, telemetry shows users approve about 93% of prompts - approval fatigue is widespread.
Q5: Why does bare srt deny all writes, while the Claude Code integration allows working-directory writes?
A5: Two layers, two defaults. Standalone srt follows secure-by-default with everything denied; the Claude Code integration pre-approves working-directory and per-user temp writes so the agent can function, and its default read surface is much wider (including ~/.ssh). For stricter guarantees, tighten explicitly with sandbox.filesystem.denyRead/denyWrite and sandbox.credentials.files, and enable sandbox.failIfUnavailable.
Related reading
- Agent Concurrency Runtime Comparison: our companion comparison on choosing between suspended, isolated, and resident agent runtimes.
- Five-Way Agent Isolation Comparison: our August 19 piece covering Firecracker, CubeSandbox, agent-sandbox, E2B, and Daytona - the container/virtualization route this article deliberately skips.
- AWS Infinity Agent Runtime Open-Source Resource: the companion open-source piece, including a deep dive into suspend-based runtimes.
This article is based on public materials (repository data and issue status as measured on 2026-10-25). Install commands and configuration are quoted from official sources; secondary ones are tagged inline. Not security or compliance advice.