Anthropic Sandbox Runtime (srt)
A lightweight sandboxing tool for enforcing filesystem and network restrictions on arbitrary processes at the OS level, without requiring a container.
srt uses native OS sandboxing primitives (sandbox-exec on macOS, bubblewrap on Linux) and proxy-based network filtering. It can be used to sandbox the behaviour of agents, local MCP servers, bash commands and arbitrary processes.
Beta Research Preview
The Sandbox Runtime is a research preview developed for Claude Code to enable safer AI agents. It's being made available as an early open source preview to help the broader ecosystem build more secure agentic systems. As this is an early research preview, APIs and configuration formats may evolve. We welcome feedback and contributions to make AI agents safer by default!
Installation
npm install -g @anthropic-ai/sandbox-runtime
Basic Usage
# Network restrictions
$ srt "curl anthropic.com"
Running: curl anthropic.com
<html>...</html> # Request succeeds
$ srt "curl example.com"
Running: curl example.com
Connection blocked by network allowlist # Request blocked
# Filesystem restrictions
$ srt "cat README.md"
Running: cat README.md
# Anthropic Sandb... # Current directory access allowed
$ srt "cat ~/.ssh/id_rsa"
Running: cat ~/.ssh/id_rsa
cat: /Users/ollie/.ssh/id_rsa: Operation not permitted # Specific file blocked
Overview
This package provides a standalone sandbox implementation that can be used as both a CLI tool and a library. It's designed with a secure-by-default philosophy tailored for common developer use cases: processes start with minimal access, and you explicitly poke only the holes you need.
Key capabilities:
- Network restrictions: Control which hosts/domains can be accessed via HTTP/HTTPS and other protocols
- Filesystem restrictions: Control which files/directories can be read/written
- Unix socket restrictions: Control access to local IPC sockets
- Violation monitoring: On macOS, tap into the system's sandbox violation log store for real-time alerts
Example Use Case: Sandboxing MCP Servers
A key use case is sandboxing Model Context Protocol (MCP) servers to restrict their capabilities. For example, to sandbox the filesystem MCP server:
Without sandboxing (.mcp.json):
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem"]
}
}
}
With sandboxing (.mcp.json):
{
"mcpServers": {
"filesystem": {
"command": "srt",
"args": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
}
}
}
Then configure restrictions in ~/.srt-settings.json:
{
"filesystem": {
"denyRead": [],
"allowWrite": ["."],
"denyWrite": ["~/sensitive-folder"]
},
"network": {
"allowedDomains": [],
"deniedDomains": []
}
}
Now the MCP server will be blocked from writing to the denied path:
> Write a file to ~/sensitive-folder
✗ Error: EPERM: operation not permitted, open '/Users/ollie/sensitive-folder/test.txt'
How It Works
The sandbox uses OS-level primitives to enforce restrictions that apply to the entire process tree:
- macOS: Uses
sandbox-exec with dynamically generated Seatbelt profiles
- Linux: Uses bubblewrap for containerization with network namespace isolation
- Windows: Runs the sandboxed process under a dedicated
srt-sandbox local user account, with a Windows Filtering Platform egress fence keyed on that account's SID and per-session explicit ACEs on the working tree
Dual Isolation Model
Both filesystem and network isolation are required for effective sandboxing. Without file isolation, a compromised process could exfiltrate SSH keys or other sensitive files. Without network isolation, a process could escape the sandbox and gain unrestricted network access.
Filesystem Isolation enforces read and write restrictions:
- Read (deny-then-allow pattern): By default, read access is allowed everywhere. You can deny broad regions (e.g.,
/Users) and then re-allow specific paths within them (e.g., .). allowRead takes precedence over denyRead — the opposite of write, where denyWrite takes precedence over allowWrite. A denyRead entry that is more specific than the allowRead region it falls inside (e.g. denyRead: ["**/.env"] or ["./secrets"] with allowRead: ["."]) still stays denied.
- Write (allow-only pattern): By default, write access is denied everywhere. You must explicitly allow paths (e.g.,
., /tmp). An empty allow list means no write access.
Network Isolation (allow-only pattern): By default, all network access is denied. You must explicitly allow domains. An empty allowedDomains list means no network access. Network traffic is routed through proxy servers running on the host:
Linux: Requests are routed via the filesystem over a Unix domain socket. The network namespace of the sandboxed process is removed entirely, so all network traffic must go through the proxies running on the host (listening on Unix sockets that are bind-mounted into the sandbox)
macOS: The Seatbelt profile allows communication only to a specific localhost port. The proxies listen on this port, creating a controlled channel for all network access
Windows: A machine-wide WFP filter set blocks all outbound connections originating from the srt-sandbox account except loopback to the proxy port range. The proxies listen inside that range, creating a controlled channel for all network access
Both HTTP/HTTPS (via HTTP proxy) and other TCP traffic (via SOCKS5 proxy) are mediated by these proxies, which enforce your domain allowlists and denylists.
For more details on sandboxing in Claude Code, see:
Architecture
src/
├── index.ts # Library exports
├── cli.ts # CLI entrypoint (srt command)
├── utils/ # Shared utilities
│ ├── debug.ts # Debug logging
│ ├── settings.ts # Settings reader (permissions + sandbox config)
│ ├── platform.ts # Platform detection
│ └── exec.ts # Command execution utilities
└── sandbox/ # Sandbox implementation
├── sandbox-manager.ts # Main sandbox manager
├── sandbox-schemas.ts # Zod schemas for validation
├── sandbox-violation-store.ts # Violation tracking
├── sandbox-utils.ts # Shared sandbox utilities
├── http-proxy.ts # HTTP/HTTPS proxy for network filtering
├── socks-proxy.ts # SOCKS5 proxy for network filtering
├── linux-sandbox-utils.ts # Linux bubblewrap sandboxing
├── macos-sandbox-utils.ts # macOS sandbox-exec sandboxing
└── windows-sandbox-utils.ts # Windows srt-win sandboxing
Usage
The srt command (Anthropic Sandbox Runtime) wraps any command with security boundaries:
# Run a command in the sandbox
srt echo "hello world"
# With debug logging
srt --debug curl https://example.com
# Specify custom settings file
srt --settings /path/to/srt-settings.json npm install
As a library
import {
SandboxManager,
type SandboxRuntimeConfig,
} from '@anthropic-ai/sandbox-runtime'
import { spawn } from 'child_process'
// Define your sandbox configuration
const config: SandboxRuntimeConfig = {
network: {
allowedDomains: ['example.com', 'api.github.com'],
deniedDomains: [],
},
filesystem: {
denyRead: ['~/.ssh'],
allowWrite: ['.', '/tmp'],
denyWrite: ['.env'],
},
}
// Initialize the sandbox (starts proxy servers, etc.)
await SandboxManager.initialize(config)
// Wrap a command with sandbox restrictions
const sandboxedCommand = await SandboxManager.wrapWithSandbox(
'curl https://example.com',
)
// Execute the sandboxed command
const child = spawn(sandboxedCommand, { shell: true, stdio: 'inherit' })
// Handle exit and cleanup after child process completes
child.on('exit', async code => {
console.log(`Command exited with code ${code}`)
// Cleanup when done (optional, happens automatically on process exit)
await SandboxManager.reset()
})
Violation attribution (commandId / commandText). Violations observed while a wrapped command runs (seatbelt log lines, seccomp events, proxy denies) are stored under an attribution key, and annotateStderrWithSandboxFailures(key, stderr) / getViolationsForCommand(key) look them up by that same key. By default the key is the wrapped string itself. Pass an opaque per-invocation commandId (e.g. a tool-use id) to key by that instead — recommended: keys compare on their first 100 characters, so long commands sharing a prefix would otherwise cross-attribute, and a rerun of the same text would inherit the earlier run's events. If the string you execute is not the command the invocation represents (e.g. you wrap an assembled source <snapshot> && eval '<cmd>'), also pass commandText: '<cmd>': it is what ignoreViolations command patterns match against and what each violation reports as its command.
const wrapped = await SandboxManager.wrapWithSandbox(
assembledCommand, // what actually runs
undefined,
undefined,
undefined,
{ commandId: invocationId, commandText: rawCommand },
)
// ... run it ...
const annotated = SandboxManager.annotateStderrWithSandboxFailures(invocationId, stderr)
Available exports
// Main sandbox manager
export { SandboxManager } from '@anthropic-ai/sandbox-runtime'
// Violation tracking
export { SandboxViolationStore } from '@anthropic-ai/sandbox-runtime'
// TypeScript types
export type {
SandboxRuntimeConfig,
NetworkConfig,
FilesystemConfig,
IgnoreViolationsConfig,
SandboxAskCallback,
FsReadRestrictionConfig,
FsWriteRestrictionConfig,
NetworkRestrictionConfig,
} from '@anthropic-ai/sandbox-runtime'
Configuration
Settings File Location
By default, the sandbox runtime looks for configuration at ~/.srt-settings.json. You can specify a custom path using the --settings flag:
srt --settings /path/to/srt-settings.json <command>
Complete Configuration Example
{
"network": {
"allowedDomains": [
"github.com",
"*.github.com",
"lfs.github.com",
"api.github.com",
"npmjs.org",
"*.npmjs.org"
],
"deniedDomains": ["malicious.com"],
"allowUnixSockets": ["/var/run/docker.sock"],
"allowLocalBinding": false
},
"filesystem": {
"denyRead": ["~/.ssh"],
"allowRead": [],
"allowWrite": [".", "src/", "test/", "/tmp"],
"denyWrite": [".env", "config/production.json"]
},
"ignoreViolations": {
"*": ["/usr/bin", "/System"],
"git push": ["/usr/bin/nc"],
"npm": ["/private/tmp"]
},
"enableWeakerNestedSandbox": false,
"enableWeakerNetworkIsolation": false,
"allowAppleEvents": false
}
Configuration Options
Network Configuration
Uses an allow-only pattern - all network access is denied by default.
network.allowedDomains - Array of allowed domains (supports wildcards like *.example.com). Empty array = no network access. An optional :port suffix (api.example.com:443, *.example.com:8443) restricts an entry to that destination port; entries without a port match any port.
- IPv6 literals must be bracketed, RFC 3986-style:
[::1], [2001:db8::1]:443. An unbracketed multi-colon entry is rejected as ambiguous (2001:db8::1:443 is itself a valid address).
network.deniedDomains - Array of denied domains (checked first, takes precedence over allowedDomains). Same :port suffix, and a bare * (or *:22) is accepted for deny-all.network.deniedDomainReasons - Optional map from a deniedDomains entry (matched by exact string) to a model-facing reason that appears in the <sandbox_violations> line when that entry denies a connection — say what is blocked and the sanctioned alternative (e.g. {"github.com:22": "SSH pushes to GitHub are blocked; use an https:// remote"}). Entries without a reason report a generic one. For SSH destinations (port 22), the reason is also delivered in-band: an SSH client tunneled through a no-auth SOCKS ProxyCommand (e.g. BSD nc -X 5) receives a pre-key-exchange SSH disconnect whose description is the reason, which OpenSSH prints verbatim — keep such reasons under ~400 ASCII characters, imperative first, since OpenSSH truncates and escapes non-ASCII.network.allowLocalBinding - Allow binding to local ports (boolean, default: false)
TLS termination (network.tlsTerminate, experimental): when set, HTTPS CONNECTs are terminated in-process so SRT can see (and filter, via network.filterRequest) the decrypted requests. The sandboxed process is pointed at a trust bundle containing the MITM CA (caCertPath/caKeyPath, or an ephemeral CA if omitted) plus the host's regular roots, so proxy-minted certificates and real upstream certificates both verify.
network.tlsTerminate.excludeDomains - Domain patterns (same syntax as allowedDomains) that are not terminated. Matching CONNECTs are tunnelled opaquely instead: they are still subject to the domain allowlist, but the client inside the sandbox completes its own TLS handshake with the real upstream, and filterRequest / credential injection do not apply to their HTTPS traffic. Use this for the two cases TLS termination fundamentally breaks:
- mTLS upstreams - only the in-sandbox client holds the client certificate, so the proxy cannot re-originate the connection on its behalf.
- Certificate-pinning clients - clients that verify the upstream's identity themselves (custom CAs, SAN pinning) and reject the MITM certificate.
network.tlsTerminate.extraCaCertPaths - Paths to PEM CA certificate files appended to that trust bundle, after the MITM CA and the host's regular roots. Excluded (non-terminated) hosts are verified by the client inside the sandbox, and the trust env vars SRT sets (SSL_CERT_FILE, GIT_SSL_CAINFO, ...) replace each tool's own trust configuration, so a site-local root (e.g. an internal mTLS CA) must be in the bundle or those hosts can never be verified. Only the CERTIFICATE blocks of each file are copied into the bundle (anything else, e.g. a private key in a combined PEM, is never exposed to the sandbox); files that are missing, unreadable, or contain no PEM CERTIFICATE block are skipped, so it is safe to list paths that exist on only some hosts.
{
"network": {
"allowedDomains": ["*.example.com", "internal-mtls.example.net"],
"deniedDomains": [],
"tlsTerminate": {
"excludeDomains": ["internal-mtls.example.net"],
"extraCaCertPaths": ["/etc/internal-mtls-roots.pem"]
}
}
}
Unix Socket Settings (platform-specific behavior):
| Setting |
macOS |
Linux |
allowUnixSockets: string[] |
Allowlist of socket paths |
Ignored (seccomp can't filter by path) |
allowAllUnixSockets: boolean |
Allow all sockets |
Disable seccomp blocking |
Unix sockets are blocked by default on both platforms.
- macOS: Use
allowUnixSockets to allow specific paths (e.g., ["/var/run/docker.sock"]), or allowAllUnixSockets: true to allow all.
- Linux: Blocking uses seccomp filters (x64/arm64 only). If seccomp isn't available, sockets are unrestricted and a warning is shown. Use
allowAllUnixSockets: true to explicitly disable blocking.
Filesystem Configuration
Uses two different patterns:
Read restrictions (deny-then-allow pattern) - all reads allowed by default:
filesystem.denyRead - Array of paths to deny read access. Empty array = full read access.filesystem.allowRead - Array of paths to re-allow read access within denied regions (takes precedence over denyRead). Note: this is the opposite of write, where denyWrite takes precedence over allowWrite.
Write restrictions (allow-only pattern) - all writes denied by default:
filesystem.allowWrite - Array of paths to allow write access. Empty array = no write access.filesystem.denyWrite - Array of paths to deny write access within allowed paths (takes precedence over allowWrite)
Path Syntax (macOS):
Paths support git-style glob patterns on macOS, similar to .gitignore syntax:
* - Matches any characters except / (e.g., *.ts matches foo.ts but not foo/bar.ts)** - Matches any characters including / (e.g., src/**/*.ts matches all .ts files in src/)? - Matches any single character except / (e.g., file?.txt matches file1.txt)[abc] - Matches any character in the set (e.g., file[0-9].txt matches file3.txt)
Examples:
"allowWrite": ["src/"] - Allow write to entire src/ directory"allowWrite": ["src/**/*.ts"] - Allow write to all .ts files in src/ and subdirectories"denyRead": ["~/.ssh"] - Deny read to SSH directory"denyRead": ["/Users"], "allowRead": ["."] - Deny read to all of /Users, but re-allow the current directory"denyWrite": [".env"] - Deny write to .env file (even if current directory is allowed)
Path Syntax (Linux):
Linux currently does not support glob matching. Use literal paths only:
"allowWrite": ["src/"] - Allow write to src/ directory"denyRead": ["/home/user/.ssh"] - Deny read to SSH directory"denyRead": ["/home"], "allowRead": ["."] - Deny read to all of /home, but re-allow the current directory
All platforms:
- Paths can be absolute (e.g.,
/home/user/.ssh) or relative to the current working directory (e.g., ./src)
~ expands to the user's home directory
Other Configuration
ignoreViolations - Object mapping command patterns to arrays of paths where violations should be ignoredenableWeakerNestedSandbox - Enable weaker sandbox mode for Docker environments (boolean, default: false)javaAgentJarPath - macOS/Linux: absolute path to srt-proxy-agent.jar, the JVM agent injected via JAVA_TOOL_OPTIONS (see "JVM tools" under Network Isolation). Only needed by consumers that bundle sandbox-runtime and ship the jar separately; a normal npm install finds it under vendor/java-proxy-agent/.enableWeakerNetworkIsolation - Allow access to com.apple.trustd.agent in the macOS sandbox (boolean, default: false). This is needed for Go programs (gh, gcloud, terraform, kubectl, etc.) to verify TLS certificates when using httpProxyPort with a MITM proxy and custom CA. Security warning: enabling this opens a potential data exfiltration vector through the trustd service.allowAppleEvents - Allow sending Apple Events and Launch Services open requests from the macOS sandbox (boolean, default: false). Without this, commands like open, osascript, and anything that opens URLs or scripts other apps via AppleScript fail with AppleScript error -600 ("Application isn't running") or LaunchServices errors (-10822
srt (Anthropic Sandbox Runtime) is a lightweight sandboxing tool that enforces filesystem and network restrictions on arbitrary processes at the OS level without needing a container, built to safely sandbox AI agents, local MCP servers, and bash commands.