Sandbox Runtime: Lightweight OS-Level Process Isolation for Secure Agent Execution
Anthropic’s Sandbox Runtime (srt) is a lightweight, open-source tool designed to enforce filesystem and network restrictions on arbitrary processes at the operating system level. Unlike container-based solutions, srt uses native OS sandboxing primitives—Seatbelt on macOS, bubblewrap on Linux, and a dedicated user account with Windows Filtering Platform (WFP) rules on Windows—to create secure execution environments without requiring full containerization. Developed for Claude Code, srt is now available as a research preview to help the broader AI ecosystem build more secure agentic systems.
The tool operates under a secure-by-default philosophy, where processes start with minimal permissions. Users explicitly define the access boundaries for filesystems, networks, and Unix sockets, ensuring that only necessary permissions are granted. This approach minimizes attack surfaces while maintaining flexibility for legitimate use cases, such as sandboxing AI agents, local Model Context Protocol (MCP) servers, or arbitrary shell commands.
Sandbox Runtime is distributed under the Apache 2.0 license and is implemented in TypeScript, making it accessible for integration into existing workflows. The project is actively maintained, with recent updates addressing edge cases in filesystem and network isolation, as documented in its release notes.
How It Works
Sandbox Runtime enforces restrictions through a dual-isolation model, combining filesystem and network controls to prevent common attack vectors. Without both layers, a compromised process could exfiltrate sensitive files or escape network constraints. The tool achieves this through OS-specific mechanisms:
- macOS: Uses sandbox-exec with dynamically generated Seatbelt profiles to restrict process capabilities. Network traffic is funneled through a localhost proxy, ensuring all outbound connections are mediated by the sandbox’s allowlists.
- Network access is routed via Unix domain sockets to proxies running on the host, which enforce domain-based allowlists.
- Windows Filtering Platform (WFP) rules block all outbound traffic except loopback connections to the proxy’s port range, creating a controlled egress channel.
Filesystem isolation operates on two distinct patterns:
- Read Access (Deny-Then-Allow): By default, read operations are permitted everywhere. Users can deny broad regions (e.g., /Users on macOS or /home on Linux) and then re-allow specific paths (e.g., the current directory .). Deny rules take precedence unless overridden by more specific allow rules. For example, denying access to /.env or ./secrets within an allowed directory (.) ensures those paths remain inaccessible.
- Write Access (Allow-Only): Write operations are denied by default. Users must explicitly allow paths (e.g., ., /tmp) for any modifications. An empty allowlist results in no write permissions at all.
Network isolation follows an allow-only pattern, where all outbound traffic is blocked by default. Users must explicitly define allowed domains in configuration files. Traffic is mediated through proxies:
- HTTP/HTTPS: Routed via an HTTP proxy that validates domains against allowlists before forwarding requests.
- Other TCP Traffic: Handled by a SOCKS5 proxy, which similarly enforces domain restrictions. Proxies on all platforms listen on controlled channels (Unix sockets on Linux, localhost ports on macOS, or WFP-filtered ranges on Windows), ensuring no unapproved connections escape the sandbox.
Use Cases
Sandbox Runtime is primarily designed to secure AI agents and tool execution environments, but its flexibility extends to broader developer workflows.
- Sandboxing AI Agents: Claude Code uses srt to contain agent actions, ensuring that commands executed by AI models adhere to predefined security boundaries. For example, an agent might be restricted from accessing sensitive files or connecting to unauthorized domains without explicit approval.
- Sandbox Runtime can wrap MCP servers (e.g., filesystem or network servers) to enforce restrictions such as blocking writes to sensitive directories or limiting network access to specific domains. Configuration is managed via .srt-settings.json, where users define allowlists and denylists for both filesystem and network operations.
- Isolating Arbitrary Commands: Developers can wrap any command—from curl requests to npm install—in the sandbox to enforce consistent security policies. For example, restricting a command to only access anthropic.com while blocking all other domains prevents unintended data leaks or exfiltration.
- Dynamic Configuration Updates: The --control-fd flag enables real-time adjustments to network allowlists during command execution. This is useful for scenarios where network access requirements change dynamically, such as in CI/CD pipelines or interactive development environments. Filesystem rules, however, are compiled at sandbox initialization and cannot be modified mid-execution.
In Claude Code, the sandbox integrates with the /sandbox panel, allowing users to configure modes (auto-allow or regular permissions), override blocked commands, and manage dependencies like bubblewrap or socat. On Linux, additional steps may be required to configure AppArmor or WSL2 for proper isolation.
Key Features and Capabilities
- OS-Level Isolation: Uses native sandboxing primitives to enforce restrictions without full container overhead.
- Granular Filesystem Controls: Implements deny-then-allow for reads and allow-only for writes, with support for path-specific exceptions.
- Network Filtering: Mediates all outbound traffic through proxies (HTTP/SOCKS5) with domain-based allowlists.
- Violation Monitoring: On macOS, taps into the system’s sandbox violation log store to provide real-time alerts for policy breaches.
- Filesystem rules remain static during execution.
- Secure Defaults: Processes start with minimal permissions, requiring explicit configuration for any access. Default behavior denies all network access and write operations outside predefined paths.
- Cross-Platform Compatibility: Works on macOS, Linux (including WSL2), and Windows (via WSL2). Native Windows support is limited to the dedicated user account and WFP integration.
- Integration with Claude Code: Directly used in Claude Code to sandbox Bash, PowerShell, and Monitor commands. Configuration is managed via .claude/settings.local.json or command-line flags, with options to enforce sandboxing organization-wide.
- Dependency Management: Checks for required tools (bubblewrap, socat, seccomp filter) and provides clear error messages if dependencies are missing. On Ubuntu 24.04+, additional AppArmor configuration may be needed for bubblewrap to function correctly.
- Error Handling: Fails explicitly if configuration files are invalid or unreadable, rather than falling back to weaker defaults. Provides detailed error messages for sandbox violations, including blocked paths or domains.
Recent releases have focused on refining filesystem and network isolation. For example, version 0.0.77 introduced fixes to ensure deny rules are not bypassed by root paths or symlinked directories, while version 0.0.76 added support for dropping root capabilities on Linux and rejecting allowlisted hostnames that resolve to private IP ranges.
Technical Architecture
Key components include:
- Library Exports (index.ts): Entry point for programmatic use, enabling integration into larger applications.
- CLI Entrypoint (cli.ts): Provides the srt command-line tool for wrapping arbitrary commands with sandboxing.
- Proxy Implementations (http-proxy.ts, socks-proxy.ts): Handle network traffic mediation, validating domains against allowlists before forwarding requests.
- macos-sandbox-utils.ts: Generates Seatbelt profiles and configures localhost proxies.
- windows-sandbox-utils.ts: Sets up WFP rules and dedicated user accounts for isolation.
- Violation Tracking (sandbox-violation-store.ts): Logs and sanitizes sandbox violation events for debugging and monitoring.
Configuration and Usage
Sandbox Runtime can be used as both a CLI tool and a library.
By default, Sandbox Runtime applies conservative restrictions: no network access, no writes outside default paths, and unrestricted reads. Users must explicitly define allowlists or denylists in a settings file (e.g., ~/.srt-settings.json) to grant additional permissions. If the settings file is missing or invalid, the tool exits with an error rather than falling back to weaker defaults.
"allowedDomains": [],
Network access is entirely denied unless explicitly allowed.
For dynamic updates, --control-fd reads JSON configuration objects from a file descriptor (e.g., a pipe) and applies them in real time. Only network allowlists/denylists are updated mid-execution; filesystem rules remain static.
The tool integrates with Claude’s permission system, ensuring that commands outside sandbox boundaries still adhere to user-defined rules.
Integration with Claude Code
Claude Code leverages Sandbox Runtime to provide a secure execution environment for Bash, PowerShell, and Monitor commands. The sandbox operates in two modes:
- Auto-Allow: Commands run without explicit approval if they comply with sandbox rules. Network access to new domains triggers a classifier review within the command itself, reducing permission prompts.
- Regular Permissions: Commands follow the standard permission flow, requiring explicit approval even when sandboxed. This mode offers finer-grained control but increases user interaction.
The sandbox enforces the same filesystem and network restrictions in both modes; the difference lies in approval workflows. For instance, rm or rmdir commands targeting critical paths still prompt for approval, even in auto-allow mode.
Claude Code’s sandbox panel provides visibility into dependencies (bubblewrap, socat, seccomp filter) and allows users to configure overrides, such as enabling sandboxing globally or failing commands if dependencies are missing. On Linux, additional steps may be required to configure AppArmor or WSL2 for proper isolation. The tool’s design ensures that sandbox violations are clearly reported, with options to retry commands outside the sandbox if necessary.