Anthropic Sandbox Runtime

Anthropic Sandbox Runtime (srt) enforces filesystem and network restrictions on arbitrary processes at the operating-system level rather than through containerization. It uses native OS primitives — sandbox-exec/Seatbelt profiles on macOS, bubblewrap with network-namespace isolation on Linux, and a dedicated restricted user account paired with Windows Filtering Platform (WFP) egress rules on Windows — so a wrapped command runs with a locked-down process tree instead of inside a VM or Docker layer.

It was built to sandbox AI coding agents (Claude Code among them), local MCP servers, and arbitrary bash commands: filesystem access is deny-then-allow for reads and allow-only for writes, network access is allow-only by domain via bundled HTTP/SOCKS proxies, and credential-masking logic redacts secrets found in environment variables, mounted files, and even AWS SigV4-signed request bodies so a compromised process can’t exfiltrate them even over an allowed path. It ships as both a CLI (srt <command>) and an importable TypeScript library (SandboxManager) for embedding the same restrictions programmatically.

What You Get

• A srt CLI that wraps any shell command with sandboxing in one invocation, with a JSON settings file (~/.srt-settings.json) for reusable policy.
• A programmatic SandboxManager API (initialize, wrapWithSandbox, reset) for embedding the same restrictions inside a Node.js host application.
• Deny-then-allow filesystem read rules and allow-only filesystem write rules, evaluated per path with glob and symlink-boundary handling.
• Allow-only network access enforced through bundled HTTP and SOCKS5 proxies, with per-domain wildcard patterns and optional :port scoping.
• Credential-masking for environment variables, mounted files, and AWS SigV4-signed requests, so secrets stay redacted even across an allowed network path.
• A native Windows implementation — a dedicated srt-sandbox user account plus machine-wide WFP egress filters — instead of relying on containers or WSL.

Common Use Cases

• Sandboxing an AI coding agent (e.g. Claude Code) so it can only read/write an approved set of paths and reach an approved set of domains.
• Wrapping a local MCP server’s process so a compromised or misbehaving server can’t read SSH keys or exfiltrate data over the network.
• Running untrusted npm install/build scripts with filesystem writes restricted to the project directory and /tmp.
• Enforcing an allowlist of package-registry and CI domains for a build step, blocking everything else by default.
• Auditing violations: tapping the real-time sandbox violation log (macOS) or seccomp/proxy denial events (Linux) to see what a wrapped process tried and failed to do.

Under The Hood

Architecture The CLI (src/cli.ts, built on Commander) loads or defaults a SandboxRuntimeConfig and hands it to SandboxManager (src/sandbox/sandbox-manager.ts, ~2,400 lines), which is the central orchestrator: it starts an HTTP proxy (http-proxy.ts) and a SOCKS proxy (socks-proxy.ts) behind a multiplexing front (mux-proxy.ts), resolves an optional upstream parent proxy (parent-proxy.ts), and then delegates the actual process-wrapping to one of three platform-specific modules — macos-sandbox-utils.ts (Seatbelt), linux-sandbox-utils.ts (bubblewrap + a custom seccomp filter generator) or windows-sandbox-utils.ts (a vendored native srt-win executable driving WFP and a dedicated OS user). A parallel credential-protection layer (credential-sentinel.ts, credential-mask-files.ts, credential-mask-env.ts, credential-aws-pairs.ts) and an optional TLS-terminating MITM proxy (mitm-ca.ts, mitm-leaf.ts, tls-terminate-proxy.ts) sit alongside the network layer so secrets can be masked and HTTPS bodies inspected even on domains the sandbox allows. Violations from every platform funnel into a shared SandboxViolationStore for consistent attribution and querying.

Tech Stack TypeScript on Node.js (>=20.11.0), using Commander for the CLI, Zod for runtime config validation (sandbox-config.ts, sandbox-schemas.ts), node-forge for the MITM certificate authority, and @pondwader/socks5-server for the bundled SOCKS proxy. Native helpers are vendored and built separately: a seccomp filter binary and a Rust-based srt-win executable are compiled via Bun build scripts, and a small Java proxy agent supports sandboxing JVM processes. CI runs the full integration suite across six OS/architecture legs (Linux and macOS on x86-64/arm64, Windows on x86-64/arm64) on every push and pull request.

Code Quality The test suite is extensive — several hundred test() cases across roughly fifty files, covering macOS Seatbelt profile generation, Linux bubblewrap/seccomp behavior, Windows WFP and ACL handling, credential masking (including a full AWS SigV4 signing conformance suite), TLS termination, symlink and glob edge cases, and proxy violation reporting. The project runs on the Bun test runner, is fully typed with exported public types, and is gated by ESLint, Prettier, and a Husky pre-commit hook running lint-staged. Source comments are notably dense and rationale-driven, explaining non-obvious platform tradeoffs (e.g. why the control-fd reader picks a libuv stream vs. a blocking fs read per platform) rather than restating the code.

API Design The public surface (src/index.ts) re-exports a consistent set of PascalCase types and camelCase functions grouped by concern — core manager, Windows install/status, MITM CA generation, platform utilities — with Zod schemas exported alongside their TypeScript types for reuse. Getting started as a library takes a handful of calls (SandboxManager.initialize(config) → wrapWithSandbox(command) → spawn → reset()), documented with a runnable example in the README; the CLI mirrors the same options through --settings and command-line flags with per-command help text. The violation-attribution API (commandId/commandText) is more advanced but is explained inline with the exact failure mode it exists to avoid.