Picture this: You’re using an AI code assistant to auto-generate deployment scripts when a chilling thought hits—what if it accidentally deletes core configuration files or secretly sends server keys to an external domain? As AI agents (like automation tools and MCP servers) become integral to development workflows, the question of “how to keep them within safe boundaries” grows increasingly urgent.
Traditional containerization solutions are too heavy, with configurations complex enough to deter half of developers. Simple permission controls, on the other hand, are too blunt to prevent sophisticated privilege escalations. That’s where Anthropic’s open-source Sandbox Runtime (srt) comes in—a lightweight sandbox tool that leverages native OS capabilities to strike the perfect balance between granular control and usability.
Why We Need “Leashes” for AI Agents
In an era of ubiquitous AI agents, security risks often hide in the details:
- 🍄
An auto-update tool might be tricked into writing malicious scripts to /usr/bin - 🍄
An MCP server processing code could read SSH keys from ~/.sshif permissions aren’t properly restricted - 🍄
A seemingly harmless automation script might exfiltrate sensitive data via curlto unknown domains
What these scenarios share is a need to restrict both a process’s “hands and feet” (file operations) and “mouth” (network communication) without hampering its utility. Traditional solutions are either as bulky as virtual machines or as limited as chroot. srt’s brilliance lies in its direct use of the operating system’s native sandboxing capabilities (macOS’s sandbox-exec and Linux’s bubblewrap), ensuring both isolation strength and “use-and-go” lightweight performance.
What Makes srt an Effective “Security Guard” for AI Agents?
srt’s core capabilities can be summed up as “two-way control”: managing file access with one hand, regulating network communication with the other, while monitoring inter-process communication—creating a complete security perimeter.
1. Network Access: Only Trusted Domains Get In
You can precisely specify which domains can be accessed, like giving your AI agent a “whitelisted address book.” For example, you might allow access to GitHub-related domains (github.com, api.github.com) for code pulling while blocking connections to all unknown domains.
It controls not just HTTP/HTTPS but also TCP protocols like SSH and databases via SOCKS5 proxying. In testing, srt curl example.com gets blocked outright, while srt curl anthropic.com returns content normally—exactly the precision AI agents need.
2. File System: Clear Boundaries for Read/Write Permissions
srt’s file permission strategy embodies textbook-level caution:
- 🍄
Read permissions: By default, all paths are accessible (making it easy for AI agents to read code and documentation), but you can specifically block sensitive directories (e.g., adding Read(~/.ssh)to deny rules stops SSH key access entirely) - 🍄
Write permissions: Only the current working directory is writable by default (preventing system file tampering), with explicit rule additions for extensions (like Edit(src/)to allow modifications to source code directories)
The most elegant feature is “nested rules”: even when allowing writes to the current directory, you can still block sensitive files like .env (by adding Edit(.env) to deny rules), achieving “broad access with targeted restrictions.”
3. Violation Monitoring: Full Visibility of All Activities
On macOS, srt integrates directly with system sandbox logs to capture unauthorized actions in real time. Running log stream --predicate 'process == "sandbox-exec"' shows detailed records like “Attempted write to ~/sensitive blocked.” Linux users can track violations with strace, using commands like strace -f srt <command> 2>&1 | grep EPERM to easily identify blocked operations.
Under the Hood: How srt Builds Walls with OS Native Capabilities
srt’s lightness comes from not reinventing the wheel but “stringing together” the operating system’s native sandboxing capabilities to form a dual isolation network.
Cross-Platform “Building Blocks”
- 🍄
macOS: Uses sandbox-execwith dynamically generated Seatbelt profiles (Apple’s sandbox rule format) to enforce file and network restrictions directly through the system kernel - 🍄
Linux: Employs bubblewrap(bwrap) to create lightweight containers, cutting off direct network access via “network namespace isolation” and controlling file read/write permissions through bind mounts
Dual Isolation: File System + Network “Double Protection”
File system isolation relies on OS-level mandatory rules: macOS uses Seatbelt configurations to explicitly define allowed paths, while Linux uses bwrap’s bind mounts to set directory permissions as read-only or read-write.
Network isolation employs a “proxy intermediary” strategy: all network requests from within the sandbox must pass through an HTTP/SOCKS5 proxy on the host machine, where the proxy layer strictly validates domain rules. Linux even removes the sandbox’s network namespace, leaving processes “only able to see the proxy”; macOS restricts connections to proxy ports via Seatbelt, blocking potential workarounds at the source.
Hands-On Tutorial: Sandbox Your Processes in 5 Minutes
Step 1: Install srt
A single npm command (ensure Node.js is installed first):
npm install -g @anthropic-ai/sandbox-runtime
Linux users need additional dependencies (Ubuntu example):
sudo apt-get install bubblewrap socat ripgrep
macOS users should install ripgrep:
brew install ripgrep # or download binary from official website
Step 2: Basic Operations
Simply wrap commands with srt to activate protection:
# Test network restrictions: allow anthropic.com, block example.com
srt "curl anthropic.com" # Returns content successfully
srt "curl example.com" # Shows "Connection blocked"
# Test file restrictions: allow reading current directory, block SSH keys
srt "cat README.md" # Displays content normally
srt "cat ~/.ssh/id_rsa" # Errors with "Operation not permitted"
Add the --debug flag to see detailed sandbox configuration (great for rule testing):
srt --debug "npm install" # View proxy startup and permission application process
Step 3: Integrate as a Library
For tools needing built-in sandboxing, import the srt library directly (TypeScript example):
import { SandboxManager } from '@anthropic-ai/sandbox-runtime';
import { spawn } from 'child_process';
// Initialize sandbox (starts proxy and other resources)
await SandboxManager.initialize();
// Wrap the command to execute
const sandboxedCommand = await SandboxManager.wrapWithSandbox('curl https://github.com');
// Execute with inherited I/O
const child = spawn(sandboxedCommand, { shell: true, stdio: 'inherit' });
// Handle exit event
child.on('exit', (code) => {
console.log(`Command exited with code: ${code}`);
});
// Clean up resources on process exit (auto-executes)
process.on('exit', async () => {
await SandboxManager.reset();
});
Configuration Deep Dive: Customizing Your Security Rules
srt uses JSON configuration files with hierarchical merging (from user-level to project-level), letting you set global base rules while fine-tuning for specific projects.
A Practical Configuration Example
{
"sandbox": {
"enabled": true,
"network": {
"allowUnixSockets": [], // Block access to all Unix sockets (e.g., docker.sock)
"allowLocalBinding": false // Prevent local port binding
}
},
"permissions": {
"allow": [
"WebFetch(domain:github.com)", // Allow GitHub domain access
"WebFetch(domain:api.github.com)",
"Edit(src/)", // Allow writes to src directory
"Edit(test/)" // Allow writes to test directory
],
"deny": [
"Edit(.env)", // Block modifications to .env files
"Read(~/.ssh)" // Block SSH key access
]
}
}
Path Matching Techniques
- 🍄
macOS: Supports git-style glob patterns, e.g., src/**/*.tsmatches all TypeScript files under src,file?.txtmatchesfile1.txtetc. - 🍄
Linux: Currently supports literal paths only; specify precisely (e.g., /home/user/src)
Configuration File Locations
From highest to lowest priority:
-
Command-line specified: srt --settings /path/to/custom.json -
Project local: ./.claude/settings.local.json -
Project-level: ./.claude/settings.json -
User-level: ~/.claude/settings.json -
System-level: /etc/claude-code/(Linux) or/Library/Application Support/ClaudeCode/(macOS)
Real-World Scenarios: srt in Action
1. Securing MCP Servers
Model Context Protocol (MCP) servers facilitate interactions between AI agents and local resources—sandboxing them significantly reduces risk.
Unsandboxed .mcp.json configuration:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem"]
}
}
}
Simply replace the command with srt to enable sandboxing:
{
"mcpServers": {
"filesystem": {
"command": "srt",
"args": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
}
}
}
Add restrictions in ~/.claude/settings.json (like blocking writes to sensitive directories) to prevent MCP server overreach.
2. Safely Running Automated Testing Tools
Tools like Jest might trigger sandbox violations (e.g., Watchman accessing files outside allowed ranges). The solution? Disable Watchman:
srt "jest --no-watchman" # Use Jest's built-in watcher instead
3. Advanced Traffic Monitoring: Integrating mitmproxy
For deep request inspection, configure srt to use a custom proxy:
-
Start mitmproxy listening on port 8888:
mitmproxy -s custom_filter.py --listen-port 8888
-
Configure srt to use this proxy:
{
"sandbox": {
"network": {
"httpProxyPort": 8888
}
}
}
All HTTP traffic from the sandbox will now pass through mitmproxy, enabling debugging or complex filtering logic.
Security Boundaries and Limitations
While powerful, srt isn’t omnipotent. Understanding its boundaries ensures effective use:
- 🍄
Network filtering relies on proxy configuration: Some applications might ignore HTTP_PROXYenvironment variables, causing connectivity issues (proxychains integration is planned to enhance interception) - 🍄
Unix socket risks: Allowing sensitive sockets like /var/run/docker.sockcould enable sandbox escape—audit these carefully - 🍄
Limited Linux monitoring: No native violation logging yet; manual stracetracking required (automated detection is planned) - 🍄
Path permission caution: Allowing writes to $PATHdirectories or shell config files (e.g.,.bashrc) could enable privilege escalation
The official documentation emphasizes: When allowing domains like github.com, be mindful of potential data exfiltration (e.g., pushing sensitive info to private repos). Pairing with MITM proxies to audit specific API calls adds an extra security layer.
Frequently Asked Questions
Q: What’s the core difference between srt and container tools like Docker?
A: srt is a lightweight process-level sandbox that leverages native OS capabilities for fast startup and low resource usage—ideal for temporarily isolating single processes. Docker provides full containers with separate filesystems and network stacks—better suited for long-running services. Simply put: srt is like “disposable gloves,” while Docker is like an “isolation ward.”
Q: Does srt work on Windows?
A: Not currently. srt relies on macOS and Linux-specific system tools; a Windows version is in planning.
Q: How do I view violation records for sandboxed processes?
A: On macOS, use log stream --predicate 'process == "sandbox-exec"' for real-time monitoring. On Linux, track with strace—try strace -f srt <command> 2>&1 | grep EPERM.
Q: Can I block a specific subfile after allowing Edit(.)?
A: Yes. srt follows a “deny-first” principle. For example, Edit(.) allows writes to the current directory, but deny: ["Edit(.env)"] specifically blocks .env files.
Conclusion: Let AI Agents Run Free—Within Safe Limits
srt’s true value lies in balancing “security controls” with “developer experience”—you don’t sacrifice efficiency for safety or vice versa. For scenarios requiring “limited freedom” (like AI agents and automation scripts), it provides precisely calibrated constraints.
As an open-source project, srt continues to evolve: enhanced Linux violation monitoring, more flexible path matching, and stronger proxy interception are all in the pipeline. If you’re grappling with AI agent security, start with srt "your-command"—adding a lightweight yet reliable safety net to your toolchain.
After all, true security isn’t about imprisonment—it’s about defining clear boundaries: keeping legitimate operations unimpeded while blocking dangerous ones entirely.
