External sandboxes for coding agents: run Claude Code, Codex and Pi commands in a Linux guest with npx or uvx
Prime Radiant and Simon Willison released three sandbox servers, external-sandbox-v86, -container and -quicksand, that run a coding agent's commands inside a Linux guest that sees only the folders and hosts you allow. Here is how each agent connects and what stays outside.
Prime Radiant, the AI research lab behind Superpowers, published three prototype sandbox servers on November 16 that let Claude Code, Codex or Pi keep running on your Mac while the commands they execute run inside a Linux guest: two virtual machines and one Apple Container. Simon Willison wrote the announcement on the Prime Radiant blog and calls the idea the external sandbox pattern: the agent stays outside, the code it runs goes in. The project home is the GitHub repository prime-radiant-inc/external-sandbox, which holds the shared protocol, a conformance test runner and the agent integrations.
The pitch is a safety layer that does not depend on a model judging each action. Claude Code's auto mode and Codex's auto-review use AI checks to decide what is safe; the post says those appear to work well but are product features that still rely on a model getting it right, and that cheaper or local models are more prone to mistakes and easier prompt-injection victims. Commands in the sandbox see only the folders you mount, get no network unless you turn on its proxy, and can call allowed APIs with keys the proxy adds on the host side. Each of those has an exception, covered below; the biggest is that Claude Code's file tools do not go through the sandbox at all.
Quick facts
- Three servers, same localhost API: external-sandbox-v86 (Node.js, Alpine Linux in v86 WebAssembly, port 8686), external-sandbox-container (Python, Apple Containers, port 8687), external-sandbox-quicksand (Python, Microsoft's Quicksand with QEMU, port 8688).
- Install: v86 from npm with npx and Node.js 22 or later (the blog says 22.19); the two Python servers from PyPI with uvx.
- Platforms: v86 runs on macOS or Linux with Node.js. The container server needs an Apple silicon Mac, Apple's container CLI (run container system start first) and uv. Quicksand needs uv and is tested on Apple silicon macOS; there is no QEMU wheel for Intel Macs.
- License: Apache-2.0 for all three. The authors call them experimental prototypes not audited for sensitive workloads.
- First download: about 36 MB for the v86 package with its Linux image, about 100 MB of QEMU and Alpine wheels for Quicksand.
- Guest tools differ: the v86 guest is 32-bit Alpine with Bash, Python 3, Git and ripgrep but no Node or npm; the container image adds Node.js 24 LTS, npm, uv, curl and jq; Quicksand prepares a cached Alpine image with Bash, Python 3, Git and ripgrep on first use, with 2 CPUs and 1 GiB of memory by default.
What each agent actually sends into the sandbox
This is the part to read before trusting it. The three agents connect in different ways, and the coverage is not the same.
- Claude Code: only Bash tool commands go to the sandbox, through the CLAUDE_CODE_SHELL_PREFIX environment variable. Claude's own Read and Edit tools still read and change files on your Mac directly, and the integration does not change their permissions.
- Codex: process and filesystem operations go to the sandbox, including native apply_patch, through Codex's exec-server protocol at the server's /codex WebSocket endpoint. The authors' tests pass against Codex CLI 0.164.0; the protocol is marked experimental in Codex.
- Pi: the external-sandbox-pi extension replaces Pi's bash, read, write, edit, grep, find and ls tools, plus its ! and !! shortcuts. Started with --no-builtin-tools, Pi has no tool that runs on your computer even if the extension fails to load.
One more Claude Code detail comes from Claude Code's own environment-variable docs rather than the announcement: CLAUDE_CODE_SHELL_PREFIX wraps more than Bash tool calls. It also wraps hook commands, status line commands and the startup commands of stdio MCP servers; only PowerShell hooks and exec-form hooks run without it. The Prime Radiant README notes the same thing. So with the sandbox prefix set, those commands run in the Linux guest too. Our inference: a hook or MCP server that depends on macOS binaries or on host network access is likely to break there.
How to start it
The shortest path is the v86 server plus Pi. From your project directory:
npx --yes external-sandbox-v86 \
--preserve-paths --mount-rw "project=$PWD"
# second terminal, same directory
npx --yes @earendil-works/pi-coding-agent \
-e npm:external-sandbox-pi --no-builtin-tools \
--sandbox-url http://127.0.0.1:8686Pi needs version 1.5 or later for the extension, and a first-time user has to run /login inside Pi to connect a model. Once Pi's status bar shows Sandbox: ..., !uname -a should print a Linux kernel rather than Darwin. The project folder is mounted read-write at /mnt/project and, with --preserve-paths, at its original path too, so commands that mention host paths still work. Add --mount-ro name=/some/path for folders the agent may read but not change. Opening the server's port in a browser gives an in-browser terminal.
For Claude Code, clone prime-radiant-inc/external-sandbox to get the shell prefix script, then start Claude from the same project directory the server was started in. The temp directory has to sit inside the writable mount because Claude Code keeps its own bookkeeping there. The streaming wrapper needs uv and Python 3.11 or later on the host.
git clone https://github.com/prime-radiant-inc/external-sandbox.git
PREFIX_DIR="$(cd external-sandbox/claude-code && pwd)"
# from the project directory
mkdir -p .external-sandbox-claude-tmp
CLAUDE_CODE_SHELL=/bin/bash \
CLAUDE_CODE_TMPDIR="$PWD/.external-sandbox-claude-tmp" \
CLAUDE_CODE_SHELL_PREFIX="$PREFIX_DIR/claude-shell-prefix.sh" \
EXTERNAL_SANDBOX_API_URL=http://127.0.0.1:8686 \
claudeFor Codex, create a separate Codex home with an environments.toml pointing at the sandbox's /codex WebSocket endpoint, log in once with that home, then launch with --sandbox danger-full-access so Codex does not stack its own sandbox inside this one. This is the blog's setup; the authors' tests pass against Codex CLI 0.164.0, and Codex marks its exec-server protocol experimental, so newer versions may need checking.
mkdir -p ~/.codex-external-sandbox
cat > ~/.codex-external-sandbox/environments.toml <<'EOF'
default = "external-sandbox"
include_local = false
[[environments]]
id = "external-sandbox"
url = "ws://127.0.0.1:8686/codex"
connect_timeout_sec = 5
initialize_timeout_sec = 10
EOF
CODEX_HOME=~/.codex-external-sandbox codex login
CODEX_HOME=~/.codex-external-sandbox codex --sandbox danger-full-access \
-c features.shell_snapshot=false \
-c features.unified_exec_tty=false \
--cd "$PWD"Network rules and hidden API keys
With no flag, the v86 VM has no network device at all. --proxy starts with every destination denied and lets you add rules from a /proxy page in the browser UI, which also logs recent allowed and denied requests; rules added there last only until the server stops, so save them to a file for --proxy-config to keep them. Rules name an exact origin and, optionally, the HTTP methods and paths allowed, so you can permit GET on pypi.org and nothing else. The proxy sets HTTP_PROXY, HTTPS_PROXY and CA certificate variables in the guest; code that ignores them and connects directly is still blocked.
Credential replacement is the other half. A rule can say that requests to, for example, https://api.github.com carry a placeholder header, and the proxy swaps the placeholder for the real token from an environment variable set where the sandbox server starts on the host. Code inside the sandbox gets only the placeholder, through a guestEnv block that has to be in a configuration file because the /proxy page cannot change it. The authors' own caveat: an allowed host could echo the credential back in a response, so use credential rules only with services you trust and keep methods and paths narrow.
Try it with your AI. Copy this to your coding agent to start the v86 external sandbox for one project and check that commands really run inside it. It does not set up network access or credentials.
Help me run my coding agent's shell commands inside the external-sandbox-v86 server from
prime-radiant-inc. Project folder: [absolute path]. Agent: [Claude Code, Codex or Pi].
First checks, and stop if any fails: node --version is 22.19 or later; the project
folder is a git repository with no uncommitted work I care about (the sandbox mounts it
read-write, so anything run there can still change or delete files in it). For Claude
Code, also check uv is installed and Python is 3.11 or later. For Pi, check Pi is 1.5 or
later.
Then, showing me each command and waiting for my OK before running it:
1. Start the server from the project folder with npx --yes external-sandbox-v86
--preserve-paths --mount-rw "project=$PWD". Add --mount-ro only for folders I list
here: [read-only folders or none]. Wait until it prints Listening on
http://127.0.0.1:8686.
2. Test it with curl -s http://127.0.0.1:8686/exec -H 'Content-Type: application/json'
-d '{"command": "uname -m && pwd"}'. The reply is JSON; check that stdout shows a
Linux machine type and a path inside the guest such as /mnt/project.
3. Give me the launch steps for my agent from these files only: Claude Code from
external-sandbox/claude-code/README.md (git clone of
prime-radiant-inc/external-sandbox, CLAUDE_CODE_SHELL_PREFIX), Codex from
external-sandbox/codex/README.md (environments.toml in a separate CODEX_HOME, then
codex login), Pi from the external-sandbox-pi README (-e npm:external-sandbox-pi
--no-builtin-tools, then /login if I have not used Pi before).
4. Tell me plainly which of my agent's tools still run on my Mac outside the sandbox.
For Claude Code, say that Read and Edit do.
Do not install anything beyond what those READMEs name, do not read or copy credential
files, and do not delete files.Known limits
- Experimental prototypes, not audited for sensitive workloads, in the authors' words.
- Claude Code's Read and Edit tools are not sandboxed (see above).
- A read-write mount still lets the agent damage anything in that folder. Keep it under version control and use read-only mounts where you can.
- The guest is Linux, so macOS-built dependencies in the project, such as node_modules or a .venv, may need reinstalling inside the sandbox.
- The v86 API has no token authentication and is meant for trusted local processes: it binds to 127.0.0.1 and rejects browser cross-site requests, but other local processes can call it.
- Guest changes outside the mounts are disposable. On v86, tools added with --packages are reinstalled on every boot; Quicksand caches a prepared image per package list instead.
- Codex keeps its model traffic and login on the host; only process and filesystem operations go to the sandbox.
Related on claudefox
- Kanzo puts a kanban board and an MCP server for coding agents in one 4.7 MB binary
- open-code-review: a Go CLI that reviews Git diffs with a model and line-level comments
- PhoneBox turns an old Android phone into a desk panel and control deck for Windows, Linux and macOS
- Plannotator: review your coding agent's plans, diffs and messages before it acts
Problems and feedback
The authors ask for issues on the prime-radiant-inc/external-sandbox repository. If you want to build a compatible server on another technology, the PROTOCOL.md specification and the conformance runner in the same repository are the starting point.
FAQ
Does external-sandbox stop Claude Code from editing files outside my project? No. Only Claude Code's Bash commands go through the sandbox; its Read and Edit tools still run on your Mac with their normal permissions, so keep Claude Code's own permission rules in place.
Which external sandbox should I use on an Intel Mac or on Linux? external-sandbox-v86, which needs Node.js 22 or later on macOS or Linux (the blog says 22.19). The container server needs an Apple silicon Mac with Apple's container CLI, and Quicksand is tested on Apple silicon macOS and publishes no QEMU wheel for Intel Macs.
Can the sandbox reach the internet? Not by default; the VM has no network device. Start it with --proxy or --proxy-config to allow specific origins, methods and paths through a host-side proxy.
Can I run more than one sandbox at once? Yes. The v86, container and Quicksand servers use ports 8686, 8687 and 8688 by default, so all three can run side by side.
Will my hooks and MCP servers still work? Possibly not. Claude Code applies CLAUDE_CODE_SHELL_PREFIX to hook commands, status line commands and stdio MCP server startup commands as well as Bash, so those run in the Linux guest. PowerShell hooks and exec-form hooks are the exceptions and run without the prefix.
Source: Prime Radiant blog: External sandboxes for coding agents, Simon Willison: External sandboxes for coding agents, GitHub: prime-radiant-inc/external-sandbox, GitHub: prime-radiant-inc/external-sandbox-v86, GitHub: prime-radiant-inc/external-sandbox-container, GitHub: prime-radiant-inc/external-sandbox-quicksand, Claude Code docs: Environment variables
This story first appeared in the claudefox daily briefing for November 18, 2026.