Skip to content

Sandbox ​

Policies decide calls that go through Guard. A sandbox limits what a process can do when it doesn't: which files it can read and write, and which hosts it can reach. Guard can start a command, or a stdio MCP server, inside srt, the open-source Sandbox Runtime (@anthropic-ai/sandbox-runtime), on macOS and Linux.

Check the target first

Before you rely on the sandbox, run the probe on the exact image your agent uses (see Check the host).

Install srt ​

  • Install the npm package @anthropic-ai/sandbox-runtime at exactly version 0.0.77. Guard refuses any other version, and any srt that doesn't come from that package.
  • Node.js 20.11 or later.
  • macOS: sandbox-exec and rg (ripgrep).
  • Linux: bwrap (bubblewrap), socat and rg, and a non-root user that can create user namespaces with network isolation. On Ubuntu 24.04 and later the AppArmor user-namespace policy may need the host administrator's permission.

Check the host ​

sh
preworld-guard sandbox verify --executable tooling/node_modules/.bin/srt

--executable is the path to the pinned srt. The check uses only temporary files and a local HTTP service. It confirms that writing inside the workspace and reaching an approved port work, and that these fail: writing outside the workspace, writing an explicitly denied path, reading a protected file, reaching an unapproved destination, opening a direct socket, and doing any of that from a child process. It exits 0 only if every check passes. If any fails, don't treat that host as a sandbox boundary.

Keep the report (kernel, architecture, package version, CLI hash) and run the check again after upgrading the package, the OS or the image.

Run a command in the sandbox ​

sh
preworld-guard sandbox run \
  --workspace ./workspace --deny-read ~/.ssh --deny-domain '*.untrusted.example' \
  -- python agent.py
OptionMeaning
--workspaceThe working folder (default: the current folder)
--allow-read, --deny-readPaths to allow or refuse reading (repeatable)
--allow-write, --deny-writePaths to allow or refuse writing (repeatable)
--allow-domain, --deny-domainNetwork destinations to allow or refuse (repeatable)
--timeoutSeconds before the command is stopped (default 120)
--executablePath to srt (default srt)

Guard writes a one-time settings file and runs srt --settings <file> <command>. It never builds a shell string. The settings turn off srt's weaker nested sandbox, weaker network isolation, Apple Events and local port binding. The command's exit code is passed through.

Sandbox an MCP server ​

preworld-guard mcp-proxy --sandbox starts a stdio MCP server inside srt, with --sandbox-allow-read, --sandbox-deny-write and the other --sandbox-* options. Without a working srt, the proxy refuses to start. See MCP proxy.

What it doesn't replace ​

  • It is not network isolation between the agent's container and your business services. Keep network rules and test them with a connection that should fail.
  • It doesn't inspect what an allowed connection sends.
  • Results on macOS don't carry over to Linux, or to another image. Verify each target.