# Anthropic’s sandbox-runtime: Sandboxing AI Agents Without Containers
## What Is sandbox-runtime?
Anthropic released an open-source tool called **sandbox-runtime**, often shortened to **srt**, that wraps any running process in strict filesystem and network boundaries. It is the engine behind Claude Code’s sandboxed bash feature, but it is not limited to that product — any command-line tool, local agent, or MCP server can run inside it.
The tool is distributed as an npm package, `@anthropic-ai/sandbox-runtime`, and can be used either from the terminal or as a TypeScript library in your own code.
—
## Why OS-Level Sandboxing Matters
Traditional approaches to sandboxing spin up full containers or virtual machines. sandbox-runtime takes a lighter path: it uses built-in operating system features to restrict what a process can access, without adding the overhead of a container or VM.
The idea is simple but powerful. Instead of asking a user to approve every single action an AI agent takes, the agent runs inside a carefully bounded environment. It can work freely within those boundaries and only triggers a permission prompt when it needs to go beyond them.
—
## How It Works Across Operating Systems
srt adapts to whatever platform it runs on by using each operating system’s native isolation mechanisms.
– **macOS** relies on `sandbox-exec` with dynamically generated Seatbelt profiles. The only extra dependency is the `ripgrep` search tool.
– **Linux** uses `bubblewrap` with the network namespace removed, along with `socat` and `ripgrep`. On Ubuntu 24.04 and newer, a minor AppArmor adjustment is needed for user namespaces.
– **Windows** is in an alpha stage. It creates a dedicated sandbox account and applies a Windows Filtering Platform egress fence combined with explicit file access control lists.
In all cases, the sandbox applies restrictions to the entire process tree — meaning child processes, scripts, and subprocesses inherit the same boundaries.
—
## Network Traffic Flow
Network access is the trickiest part of any sandbox. srt routes all outbound traffic through HTTP and SOCKS5 proxies that run on the host machine. The sandbox itself has no direct path to the outside world.
On Linux, these proxies sit behind Unix sockets that are bind-mounted into the restricted environment. On macOS, the Seatbelt profile permits only a single localhost port for the proxies to listen on. The proxies then check every connection against a domain allowlist and denylist before forwarding traffic.
—
## The Default Security Posture
srt follows a “least privilege” philosophy out of the box:
– **Reading files** is allowed everywhere unless explicitly denied.
– **Writing files** is denied everywhere unless explicitly allowed.
– **Network connections** are denied by default; every destination host must be on an allowlist.
This means a prompt-injected agent cannot sneakily exfiltrate SSH keys, and it cannot escape the sandbox to gain broader network access. Both layers of protection are necessary — filesystem isolation without network isolation leaves data exfiltration open, and network isolation without filesystem isolation lets a compromised process break out.
—
## Configuration Example
Settings are stored in a JSON configuration file at `~/.srt-settings.json`. Here is a practical example:
“`json
{
“network”: { “allowedDomains”: [“api.github.com”, “*.npmjs.org”], “deniedDomains”: [] },
“filesystem”: { “denyRead”: [“~/.ssh”], “allowWrite”: [“.”], “denyWrite”: [“.env”] }
}
“`
This configuration allows an MCP server to reach GitHub and npm registries, blocks reads of SSH private keys, permits writes to the current directory, and protects `.env` files from being overwritten.
For MCP servers, switching to srt is as simple as changing the command from `npx` to `srt` in the `.mcp.json` file and passing the original command as arguments.
—
## The 84% Reduction in Permission Prompts
Anthropic reported internally that using sandbox-runtime reduced Claude Code permission prompts by **84%**. This is a self-reported figure from an engineering post, not an independent benchmark.
The practical benefit is real: when developers are asked to approve actions dozens of times per session, they stop reading what they are approving. A fixed sandbox boundary lets the agent operate with minimal interruption, asking for approval only at the edge of the boundary.
—
## Balancing Strictness and Usability
Writing an allowlist that is neither too strict nor too loose is the central challenge. srt provides several features to help strike that balance:
– **Wildcards and port specifications** — allow `*.npmjs.org` or restrict access to `api.example.com:443`.
– **Ask callbacks** — for hosts that do not match any rule, a callback can decide whether to block or allow and explain why.
– **Per-command allowlists** — temporarily open a registry for a single invocation of a command.
– **Live updates** — the `–control-fd` flag lets you swap network rules while a command is still running.
– **Resolved-address checks** — blocks allowed domain names that resolve to loopback or cloud metadata IPs, preventing bypass attempts.
– **Denied-domain reasons** — tells the agent which sanctioned alternative to use, such as pointing a git remote to an HTTPS URL.
—
## How It Compares to Other Sandboxing Solutions
| Feature | sandbox-runtime | Codex CLI Sandbox | Docker Sandboxes | E2B |
|—|—|—|—|—|
| Isolation method | OS primitives | OS primitives | microVM | Firecracker microVM |
| Where it runs | Local | Local | Local | Cloud or BYOC |
| Needs container/VM | No | No | Yes | Yes |
| Network default | Deny all | Off by default | Policy-dependent | On by default |
| Domain allowlist | Wildcards + ports | On/off toggle | Wildcards + ports | Wildcards |
| License | Apache-2.0 | Apache-2.0 | Not disclosed | Apache-2.0 (SDK) |
| External use | CLI + library | Built into Codex | sbx CLI | JS and Python SDKs |
srt stands out for its lightweight approach — no container or VM required — and its flexibility as both a CLI tool and a programmable library.
—
## Frequently Asked Questions
**What is sandbox-runtime built in?**
It is a Node.js package (v0.0.81 at the time of release) that runs on macOS, Linux, and Windows (alpha). It requires Node.js 22.12 or later. The unpacked package is approximately 11.4 MB and is licensed under Apache-2.0.
**Can I use srt with tools other than Claude Code?**
Yes. Any command-line program, local MCP server, or custom agent can run inside srt. It is designed to be generic, not tied to a single product.
**What happens if an agent tries to access a blocked file or host?**
The operation is refused. The violation is logged, and the agent can read the log to understand why its action was blocked. With the ask callback feature, the agent can also be given a reason and a suggested alternative.
**Is Windows fully supported?**
No. Windows support is currently in alpha. It uses a dedicated sandbox account and Windows Filtering Platform rules, but it is not yet feature-complete compared to macOS and Linux.
**Does sandbox-runtime replace Docker or virtual machines?**
Not necessarily. It is a lighter-weight alternative suited for agent sandboxing on developer machines and CI environments. For workloads requiring full OS-level isolation or reproducible environments, containers and VMs still have a role.
**Is the 84% figure verified by an independent party?**
No. The reduction in permission prompts is a self-reported internal metric from Anthropic, not from an external audit or controlled benchmark.
—
## Conclusion
Anthropic’s sandbox-runtime offers a practical, lightweight way to run AI agents and command-line tools inside strict filesystem and network boundaries. By leaning on native OS isolation primitives instead of containers, it avoids the overhead and complexity that come with VM-based approaches while still delivering meaningful security benefits.
The 84% drop in permission prompts demonstrates that OS-level sandboxing can significantly improve the developer experience when working with autonomous coding agents. The breadth of the allowlist is the most important configuration decision — too narrow and legitimate tasks fail, too broad and the sandbox provides little protection.
As a beta research preview with an alpha Windows implementation, sandbox-runtime is best suited for experimentation and local development today. Its open-source Apache-2.0 license, dual CLI-and-library design, and compatibility with any process make it a compelling foundation for anyone building or running agent-based workflows.
Thank you for reading
