Sandbox

Every shell command an agent runs, and every SKILL.md script, is confined by the operating system. The sandbox is on by default: an agent with shell and no sandbox: block runs its commands under the defaults below. An agent file can widen or narrow what its commands may touch:

The block above is exactly what an agent with no sandbox: block gets. Every key maps to something the engine enforces. The older flat spellings keep working: allowed_folders is files.write, a bare network: list is network.hosts, and env_passthrough is env. allowed_commands and allowed_imports are unchanged (see "What is not enforced").

This is enforced by the operating system, not by reading the command. The engine is srt (@anthropic-ai/sandbox-runtime), the sandbox runtime behind Claude Code: Seatbelt (sandbox-exec) on macOS, bubblewrap (bwrap) on Linux, plus a proxy outside the sandbox that admits only the hosts you list. Both SDKs run it, so the same file is confined the same way under either CLI. The restriction is inherited by anything the command spawns, so it covers pipelines, python -c and subshells, and a command cannot widen it from inside.

Measured with real srt on macOS, using the CLI's own settings:

Only shell commands and SKILL.md scripts are confined. The agent's own tools (the model, rest_request, delegate) and MCP servers run in the agent process, unconfined.

Reads are broad except under strict. Scoping reads is correct but expensive: module resolution and toolchains traverse far more of the filesystem than you would expect, so it is opt-in rather than the default.

files.write entries are relative to the agent's directory unless absolute. Every path is resolved through symlinks first, which matters on macOS where /tmp, /etc and /var all point into /private. files.read is all, or a list of folders: a list scopes reads to those folders, the write folders, the agent's folder and the system folders, as strict does. files.deny adds paths commands may never read.

Each host entry is a host name, a wildcard under a domain, a host with a port, or a group. An empty or missing list means no network at all. A URL, a path, a bare * or an address range is refused when the file loads. Traffic goes through a proxy srt runs outside the sandbox (HTTP_PROXY and friends are set inside, and Node is told to honour them), which is where the list is checked; a host that is not listed gets a 403, and a program that ignores the proxy is stopped at the socket. curl, git over https, npm, pip, Python's urllib and Node's fetch all reach a listed host.

The groups expand to exactly these hosts:

local: true lets commands connect to servers on your own machine and listen on a port. On Linux a command runs in its own network namespace: it can always listen there, where nothing outside reaches the port, and with local: true it reaches a server on localhost or 127.0.0.1 through the sandbox's proxy, which curl, pip, npm, Node and Python use; a program that opens its own socket to 127.0.0.1 (a database client, for one) does not get through. sockets lists unix sockets by path; srt honours the list on macOS only, and on Linux the policy reports it as unenforceable and grants nothing.

Anything whose name contains KEY, SECRET, TOKEN, PASSWORD, PASSWD, CREDENTIAL, PRIVATE, AUTH, SESSION or COOKIE is unset inside unless the file lists it under env. A listed name that your shell does not export is read from the .env files the CLI loads (./.env, then the profile folder's .env); nothing else from those files reaches the command, which cannot read them itself.

These apply under every confined preset, and no key removes them:

A command cannot send what it reads anywhere unless its sandbox lists hosts, but what it prints goes back to the model. That is why these are denied for reading, not only for sending.

On macOS these are patterns, so a file created during the command is covered too. On Linux the entries that exist when the command starts are denied by name, and the .env files are found by a short walk of your home directory: it looks four folder levels down, skips tool caches such as node_modules and .cache, and does not see a file created after it ran.

The opt-out is explicit, and the CLI says so when the agent loads, in the status row, in /sandbox and in webagents doctor:

Under either, commands run with your permissions. Callers other than the owner are refused shell commands unless they are confined, whatever the opt-out, and SKILL.md scripts keep running confined.

When a confined command's output shows a refusal, the tool appends one sentence naming the switch that opens it: network.hosts (or a group) for a host the proxy refused or a name that could not be resolved, network.local for a local connection or a listening port, network.sockets for a unix socket, and env for a variable or a .env read.

In the interactive chat, a host the proxy refused is asked about by name, read from srt's own log: allow it once (the command re-runs with the host for that run), always (the host is written into the agent file's network.hosts, where you can see and review it, and the command re-runs), or not at all. serve, the daemon and -p never ask; they refuse with the sentence.

Some paths stay read-only even inside an allowed folder: .git/hooks, .git/config, .claude, .webagents, .vscode, .idea, shell rc files, .gitconfig, .mcp.json and .env, and the agent's own control files: AGENT.md, every AGENT-<name>.md, WEBAGENTS.md, mcp.json and the whole .agents/skills folder. A command that could write those could grant itself permissions for the next command (a wider network:, an open access: block, a new schedule or a new agent for the daemon to serve), which would make the whole declaration advisory.

On Linux, srt denies a file only when it exists as the command starts, so an AGENT-<name>.md that a command creates is not covered there; on macOS the pattern itself is denied. Keep that in mind for a daemon on Linux, which serves every agent file that appears in its folder. The chat never reloads an agent file unasked, and says when one changed during a reply.

webagents' own install stays read-only too, when it sits in a folder commands may write. With a project-local virtual environment (.venv) or node_modules in the agent's folder, that environment, the webagents package, the sandbox engine and the node that runs it are write-denied, since a command that rewrote them would run its own code, unconfined, on the next command or the next webagents start. A different virtual environment or node_modules in the same folder stays writable. webagents doctor and webagents sandbox setup say when this applies (the install line); a command cannot pip install or npm install into that environment, so install webagents outside the folder (pipx, a global install, or a virtual environment elsewhere) if commands need to.

SKILL.md scripts always run confined. A script from a SKILL.md skill runs through srt with the agent's sandbox: settings, or strict when the agent declares none; off is refused for scripts, and --no-sandbox does not apply to them. Every skill folder is read-only to it, its own included.

A temp directory is provided, and it is not your $TMPDIR. Commands get $TMPDIR/webagents-sandbox, and TMPDIR points there inside the sandbox. npm's cache is pointed there too, because ~/.npm is not writable inside.

git init and git clone fail inside an allowed folder, because they write .git/config, which stays read-only. Commits, fetches and pushes work.

A misspelled key is an error. presets: strict stops the file from loading with a "did you mean" rather than running with the looser default.

It comes with webagents, in both SDKs:

WEBAGENTS_SRT_CLI (the absolute path of an srt install's dist/cli.js) and WEBAGENTS_SRT_NODE (a node binary) override either choice. Whichever wins, the version must be exactly 0.0.77: srt drops settings it does not know silently, so a version this SDK has not been checked against is refused rather than trusted.

What the packages cannot bring is the machine's part:

checks all of this and installs nothing. It runs one confined true through the engine, prints each check with what to do about the ones that fail (on Linux, the install line for your distribution), and exits 1 when shell commands would be refused. --json gives the same checks as one document.

It refuses, and the command does not run, whether the file declared a sandbox or the defaults apply. The refusal says what this machine lacks, then the opt-out:

That is deliberate. A sandbox that silently does nothing is the failure this feature exists to prevent, so an unavailable backend is an error rather than a downgrade.

On macOS, srt cannot start when $TMPDIR is very long (a Unix socket path is limited to 104 bytes), for example inside a deeply nested scratch folder. webagents sandbox setup says so; point TMPDIR at a short path, such as /tmp/wa.

Callers other than the owner only ever run confined. The shell tool is owner-only unless the file's access: block hands it to a group; a caller in that group is refused when the agent has opted out (sandbox: off, --no-sandbox) or the sandbox cannot run here. The owner may still run unconfined.

reports the state and the engine in use (development (default), enforced by srt 0.0.77, strict (agent file), enforced by ..., off (--no-sandbox): not confined; ...), or why there is none, with the same fix webagents sandbox setup gives. In the chat, /status shows the state and /sandbox adds the effective folders, hosts and switches.