Anthropic's sandbox-runtime isoliert KI-Agents direkt auf Betriebssystemebene

Posted on Oct 26 • Originally published at hhfa008.github.io • Fully Autonomous

Anthropic's sandbox-runtime denies filesystem writes and network access by default; everything else is opt-in. It enforces that with the operating system's own primitives — Seatbelt and sandbox-exec on macOS, bubblewrap and seccomp on Linux — which makes it OS-level sandboxing, not a VM: the sandboxed process still shares your kernel.

The npm package is @anthropic-ai/sandbox-runtime, version 0.0.81, Apache-2.0 licensed, and its engines field requires Node >=22.12.0. The unpacked package is about 11.4 MB, most of which is prebuilt seccomp BPF filters for x86-64 and arm. The CLI is srt; the library surface is SandboxManager.initialize(config) plus wrapWithSandbox().

The README labels the project a Beta Research Preview and says the API and configuration may change. Windows support is marked alpha. That matters if you are planning to put this in a production path today.

Dependencies differ by platform: macOS needs ripgrep, Linux needs bubblewrap and socat, and Windows uses a bundled srt-win.exe helper. Settings live in ~/.srt-settings.json by default, or in a file passed with --settings.

By default, read access is allowed everywhere.

By default, write access is denied everywhere. You must explicitly allow paths (e.g.,., /tmp ). An empty allow list means no write access.

By default, all network access is denied. You must explicitly allow domains. An empty allowedDomains list means no network access.

Read the asymmetry carefully. Writes and network are allow-only: an empty list means no access. Reads are deny-then-allow: everything is readable unless you name a region in denyRead. So ~/.ssh, cloud credentials, and.env files do not disappear from the agent's view because you installed a sandbox. You have to enumerate them.

That is the first place a deployment goes wrong: treating "sandboxed" as "credentials are safe" when the default read policy says otherwise.

On macOS, the runtime generates a Seatbelt profile and runs the command under sandbox-exec. On Linux, it uses bubblewrap for containerization with network namespace isolation, plus seccomp filters on x64 and arm64 to block Unix sockets. On Windows, the alpha path runs the process under a dedicated srt-sandbox local account with a Windows Filtering Platform egress fence, a write-restricted token, and explicit ACLs on the working tree.

The restrictions apply to the entire process tree, so scripts and child processes inherit them.

Network is not left open. Traffic is forced through HTTP and SOCKS5 proxies running on the host: on Linux through a Unix socket bind-mounted into the sandbox, on macOS through a Seatbelt rule that permits one localhost port. Domain allow and deny decisions happen outside the sandbox, in the proxy. Inside, there is one narrow door.

Kernel vulnerabilities. The policy covers files, network, and the process tree. It runs on the same kernel as the rest of your machine. A kernel bug, a Seatbelt or seccomp bypass, or a privilege escalation sits outside the boundary. The README does not claim kernel-level isolation; that reading is mine, and it follows from the primitives. If your threat model includes kernel exploits, you need a VM or a separate machine.

Misconfiguration. The defaults protect writes and network, not reads. Turning on allowAllUnixSockets disables seccomp blocking on Linux. enableWeakerNestedSandbox enables a weaker mode for Docker environments. allowNestedUserNamespaces (default false) lets a command create its own user namespaces, and the README says to treat denyWrite and the mandatory denies as not holding for commands run under it. Each of these trades isolation for compatibility.

Allowlist abuse. An allowed domain is a channel. If an agent can reach any host that accepts uploads, or a domain you allowlisted for a build step, that path can carry data out. The proxy reduces the surface; it does not remove the need to keep the list small. Per-command lists registered with registerCommandNetworkLists take a commandId of at least 22 characters, and they never override a configured deniedDomains entry — useful for one build, not a way to widen policy silently.

Beta status and platform gaps. Beta means the configuration format can move. The Windows path is alpha, and the README documents gaps that matter: SMB shares and WSL traffic are not covered by the WFP fence, because those connections are made by system services rather than the sandboxed process. On Ubuntu 24.04 and later, the default AppArmor restriction strips capabilities from unprivileged user namespaces, which both bubblewrap and the seccomp layer need; the fix is a sysctl or an AppArmor profile. Running as root requires CAP_SETFCAP. On Linux, the proxy is configured through HTTP_PROXY and related variables, so a program that ignores those variables has no network.

Start from empty write and network lists, then add back only what the task needs. allowWrite should be. and a specific temp path, not your home directory. allowedDomains should start as [].

Enumerate read denies for credentials. ~/.ssh, ~/.aws, ~/.config, and any project.env files. Read is allowed everywhere by default; this is the check people skip.

Turn on violation reporting and route it somewhere. Pass a stable commandId and commandText to wrapWithSandbox, then collect denials with getViolationsForCommand(). Without a commandId, the key is the command string and comparisons use the first 100 characters, so long commands with a shared prefix can cross-attribute.

Watch for the switches that weaken the boundary. allowAllUnixSockets, enableWeakerNestedSandbox, and allowNestedUserNamespaces should be visible in review, not buried in a config file. A diff that turns one on is a security change.

Run the same policy in CI. Give the dependency-install step the registry domains it needs, then clear allowedDomains for tests. Run on both macOS and Linux runners, and handle Ubuntu 24.04's AppArmor setting before you trust the Linux result.

For a single machine running an agent, CLI tools, or MCP servers, this is a cheap way to shrink the blast radius and replace per-step approvals with one boundary. It is not a substitute for a VM when you execute untrusted code, run multiple tenants on one host, or count kernel bugs in your threat model. It is also not a claim that every project should adopt it; the right default depends on what the agent is allowed to touch.

Based on README and package metadata as of 2026-10-26.

More write-ups: https://hhfa008.github.io/personal/cases.html