anthropics/sandbox-runtime

Anthropic Sandbox Runtime (srt)

What it is

• A lightweight, OS‑level sandbox that lets you run any command (or an AI‑agent server) with strict filesystem and network limits, without needing Docker or a full container.
• Built by Anthropic as a research preview for Claude Code to make autonomous agents safer.

Why it matters for AI

• Modern AI agents often run code on the host machine (e.g., model‑context‑protocol servers). If that code is compromised it could read secrets or contact the internet. srt gives developers a simple way to lock down those processes.
• Works on macOS, Linux and Windows using the native sandbox mechanisms of each platform.

Key capabilities

• Network allow‑listing / block‑listing – by default all outbound traffic is blocked; you explicitly list domains that are allowed.
• Filesystem read/write control – reads are allowed everywhere unless you deny a path; writes are denied everywhere unless you allow a path. Fine‑grained denyRead, allowRead, allowWrite, denyWrite rules.
• Unix‑socket and IPC restrictions – you can also block local socket access.
• Real‑time violation monitoring – on macOS it taps the sandbox violation log; on all platforms it records blocked network/file accesses.
• Dynamic re‑configuration – a running sandbox can receive new JSON configs over a dedicated file descriptor (--control-fd).
• Library & CLI – use the srt command directly or import the TypeScript library (@anthropic‑ai/sandbox-runtime) to embed sandboxing in your own tools.

How it works under the hood

Platform	Primitive used
macOS	sandbox‑exec with generated Seatbelt profiles
Linux	bubblewrap (bwrap) plus a custom network namespace and host‑side HTTP/SOCKS5 proxies
Windows	A dedicated local user account (srt‑sandbox) plus Windows Filtering Platform (WFP) rules

The proxies mediate all network traffic, applying the allow/deny lists before forwarding the request. Filesystem rules are baked into the sandbox profile at start‑up, so they cannot be bypassed by the child process.

Typical workflow

1. Create a settings file (~/.srt-settings.json or a custom path) describing the allowed/denied domains and file paths.
2. Wrap a command with the CLI:

   srt "curl https://example.com"
   

   The command runs inside the sandbox; any disallowed network or file access is blocked and reported.
3. (Optional) Use as a library – instantiate SandboxManager, call wrapWithSandbox to get a command string, then spawn it with child_process.spawn.
4. Monitor violations – call SandboxManager.getViolationsForCommand or use the helper that annotates stderr with a summary of blocked actions.

Example: sandboxing an MCP server

// .mcp.json before sandboxing
{
  "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] } }
}

Replace the command with srt and add a settings file that denies writes to a sensitive folder. The server will now fail with EPERM if it tries to write there.

Installation

npm install -g @anthropic-ai/sandbox-runtime

(The package ships a compiled binary srt and the TypeScript library.)

Advanced features

• --control-fd – pipe JSON config updates to a running sandbox; each line replaces the whole config after validation.
• Per‑command network allow lists – register a temporary allow list for a specific command ID, useful when a tool needs temporary access to a private registry.
• Ask callback – provide a function that is invoked when a connection does not match any rule; the callback can approve or deny the request with a custom reason.

Limitations / status

• The project is in Beta Research Preview; APIs and config formats may change.
• On Windows, filesystem ACL changes are applied only at sandbox start‑up; later config updates cannot modify them.
• The default configuration (no settings file) allows unrestricted reads, no writes, and no network access.

Where to learn more

• Claude Code Sandboxing Documentation
• Anthropic engineering blog post: Beyond Permission Prompts: Making Claude Code More Secure and Autonomous

---

TL;DR: srt is a cross‑platform CLI/library that wraps any process in a native OS sandbox, giving you fine‑grained control over what files it can read/write and which network hosts it can contact—crucial for running AI agents or server components safely without full containers.