> ## Content Index
> Fetch the complete content index at: https://blog.primeradiant.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# External sandboxes for coding agents
- URL: https://blog.primeradiant.com/external-sandboxes-for-coding-agents/
- Published: 2026-11-17T00:36:53.000Z
- Updated: 2026-11-17T01:18:45.000Z
- Description: We've been exploring safer ways to run coding agents, including against smaller, less capable models. Today we're releasing tools that let you run Claude Code, Codex or Pi in a way that ensures every command they run executes within a Linux sandbox that can only sees the folders and hosts you allow.
- Author: Simon Willison

We call this pattern **external sandboxes**.

Our work consists of three prototype sandbox implementations - one using Node.js and WebAssembly, one using Apple Containers, and one using Microsoft's [Quicksand](https://github.com/microsoft/quicksand?ref=blog.primeradiant.com) with QEMU. All three implement the same protocols, and we're including instructions for having Claude Code, Codex, and Pi execute code in those sandboxes.

The simplest demonstration uses two `npx` commands.

## Try it out with two commands

Change to your project directory and start a new sandbox using `npx`. This downloads Alpine Linux and runs it inside v86, an x86 emulator compiled to WebAssembly and hosted in Node.js. All you need is Node.js 22.19 or later:

```bash
npx --yes external-sandbox-v86 \
  --preserve-paths --mount-rw "project=$PWD"

```

Then, in a second terminal in the same directory, start a [Pi](https://pi.dev/?ref=blog.primeradiant.com) coding agent like this. If you haven't used Pi before you'll need to run `/login` inside the agent to grant it access to a model.

```bash
npx --yes @earendil-works/pi-coding-agent \
  -e npm:external-sandbox-pi --no-builtin-tools \
  --sandbox-url http://127.0.0.1:8686

```

Run `!uname -a` in Pi and you'll see the following, showing that your commands are running in Alpine Linux:

```
Linux (none) 6.12.114-0-virt #1-Alpine SMP PREEMPT_DYNAMIC 2026-10-21 12:19:03 i686 Linux

```

The Pi coding agent can now execute commands and read and write files in the project folder, but will not be able to access anything else on your machine.

![Pi running in a terminal. The !uname -a command prints a Linux kernel version, showing the command ran inside the sandbox and not on macOS.](https://storage.ghost.io/c/c2/33/c2337b7d-2a3a-4cb4-8e28-7d30596f7cd7/content/images/2026/11/sandbox-pi.png)

Claude Code and Codex both work too, with a little more setup. See below for details.

## What this gets you

- **Your agent stays on your Mac**. Pi, Claude Code, and Codex all run on your Mac as usual. The commands they execute go to the sandbox.
- **Your sandbox only sees the folders you mount.** You control which folders are available to those commands, and if they are read-only or read-write.
- **No network access unless you allow it.** By default the sandbox cannot communicate with the outside world. Add the `--proxy` option when starting the sandbox to provide access via an HTTP/HTTPS proxy to only the hosts that you allow.
- **API keys that can't be seen by the agent.** The proxy implements *credential replacement*, where requests to specific hosts have API keys added in a way that keeps those secrets outside of the sandbox and invisible to the calling agent.
- **A web UI for modifying the rules.** The web UI to the sandbox provides an in-browser terminal, tools for changing the proxy configuration and a log of requests that have been made over the network.
- **Any agent works with any sandbox.** The three sandboxes all implement the same protocol, so you can mix and match them with your preferred agents.

## As a diagram

![Diagram: on your Mac, a coding agent (Claude Code, Codex or Pi) sends commands to a sandbox server on localhost, which runs them in a Linux VM. The VM exchanges files with the folders you mount, and reaches allowed hosts on the internet through a proxy with an allow-list. Those are the only two ways out of the VM.](https://storage.ghost.io/c/c2/33/c2337b7d-2a3a-4cb4-8e28-7d30596f7cd7/content/images/2026/11/sandbox-diagram.svg)

## Why use external sandboxes?

Coding agents can get things wrong. When they make mistakes, anything that they have the ability to read or edit might end up damaged or compromised.

In an ideal world, our agents would run in secure environments where any damage they can cause is strictly limited. In the real world, many people give agents full access to both their computers and the wider world, then cross their fingers and hope for the best.

One solution to agent safety is to manually approve every action that the agent wants to take. This is a terrible way to work! It's frustratingly slow, and quickly leads to decision fatigue where we instinctively approve everything without taking time to fully understand the question.

The external sandbox pattern lets coding agents execute code and edit files inside a sandbox that gives the user control over the files, environment variables, and network connections the agents can work with - while still providing the flexibility of an agent that can run commands and write and execute code.

Anthropic and OpenAI have both invested a great deal of work into keeping their agents safe. Claude Code's [auto mode](https://code.claude.com/docs/en/auto-mode-config?ref=blog.primeradiant.com) and Codex's [auto-review](https://alignment.openai.com/auto-review/?ref=blog.primeradiant.com) both use additional AI checks to decide when it's likely safe to continue, and these appear to work well.

Those checks are features of those particular products, though, and they still rely on a model judging each action correctly. A sandbox is a protection that doesn't depend on any model's judgment. If you're keen to explore alternative models, including less expensive models or models that can run locally, concerns about safety should be front and center. These lighter models are more prone to mistakes and are easier victims of deliberate prompt injection attacks.

Our goals are to find **robust**, **trustworthy**, **easy to use** ways to have coding agents do their work in a sandbox. The commands they run should only be able to read and write the files we choose, and only make the network requests we allow.

We explored two ways to have agents use a sandbox. The first is to run the agents inside the sandboxes - this is the approach used by systems such as [Fly's Sprites](https://sprites.dev/?ref=blog.primeradiant.com). The second is to run the agent outside of the sandbox and have it send commands to a sandbox which exists separate from the agent.

We chose the second. This avoids weird behavior where the agent can modify itself or its direct environment, and keeps the sandbox boundary well defined and easier to audit.

We call this pattern "external sandboxes" because the sandbox is external to the agent, not to the computer: both sandbox and agent can run on the same machine.

## The three prototypes

These are three separate but compatible projects that exercise three different strategies for external sandboxing.

- **external-sandbox-v86** is a Node.js process that uses [**v86 in WebAssembly**](https://github.com/copy/v86?ref=blog.primeradiant.com) to run Alpine Linux. Its [npm package](https://www.npmjs.com/package/external-sandbox-v86?ref=blog.primeradiant.com) bundles a full Linux distribution that runs in a sandbox!
- **external-sandbox-container** is a Python process that wraps [**Apple Containers**](https://github.com/apple/container?ref=blog.primeradiant.com) running Linux. It can launch a container, run commands in it (sent via the protocol), then terminate it at shutdown.
- **external-sandbox-quicksand** is a Python process that runs a full **QEMU virtual machine** using Microsoft's [Quicksand](https://microsoft.github.io/quicksand/?ref=blog.primeradiant.com). QEMU and the Alpine image arrive as Python wheels, so there's nothing else to install.

The three systems offer identical localhost web APIs, but each agent connects to them in a different way:

- **Claude Code** sends only its Bash tool commands to the sandbox. Its native Read and Edit tools still run on the host, outside the sandbox.
- **Codex** sends its process and filesystem operations, including native `apply_patch`.
- **Pi** sends its `bash`, `read`, `write`, `edit`, `grep`, `find` and `ls` tools. `grep` and `find` need ripgrep in the guest, which all three default images include.

We've also produced a [specification](https://github.com/prime-radiant-inc/external-sandbox/blob/main/PROTOCOL.md?ref=blog.primeradiant.com) and conformance testing tool for that API, making it easy to build future, compatible sandbox servers on top of other technologies.

## Using it with other sandboxes and agents

The v86 Alpine Node.js server runs on port 8686 by default. The Python Apple Containers server uses port 8687, and the Python Quicksand server uses port 8688, so all three can run side by side.

The v86 server is [published to npm](https://www.npmjs.com/package/external-sandbox-v86?ref=blog.primeradiant.com) and runs with `npx`. The two Python servers are published to PyPI as [external-sandbox-container](https://pypi.org/project/external-sandbox-container/?ref=blog.primeradiant.com) and [external-sandbox-quicksand](https://pypi.org/project/external-sandbox-quicksand/?ref=blog.primeradiant.com), and run with `uvx`.

You can start the v86 Node.js server running like this:

```bash
# v86 Alpine Node.js (Node.js 22+)
npx --yes external-sandbox-v86 \
  --preserve-paths --mount-rw "project=$PWD"

```

For Apple Containers, run this:

```bash
# Python Apple Containers (Apple silicon Mac with Apple's container CLI)
container system start
uvx external-sandbox-container \
  --preserve-paths --mount-rw "project=$PWD"

```

For Quicksand, run this. The first run takes a little longer while it prepares and caches the Alpine image:

```bash
# Python Quicksand (Apple silicon Mac)
uvx external-sandbox-quicksand \
  --preserve-paths --mount-rw "project=$PWD"

```

Each server mounts the current directory read-write at `/mnt/project` and, thanks to `--preserve-paths`, at its original path too, so commands that mention host paths still work inside the sandbox. Add `--mount-ro name=/some/path` for read-only folders. Open the server's port in a browser to get the terminal and network rules UI.

### Claude Code

Unlike the other agents, Claude Code's read and edit tools do not run via the sandbox. The mount rules limit what Claude's Bash commands can touch, but Claude can still read and edit files on your Mac directly.

To run Claude Code against a sandbox, grab the shared shell prefix script from the external-sandbox repo:

```bash
git clone https://github.com/prime-radiant-inc/external-sandbox.git
PREFIX_DIR="$(cd external-sandbox/claude-code && pwd)"

```

Then run this from the project directory the server was started in (this example uses v86 on port 8686):

```bash
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 \
claude

```

8686 is the port for the v86 server; use port 8687 for Apple Containers or 8688 for Quicksand. That `.external-sandbox-claude-tmp` directory needs to be inside the writable mount, because Claude Code uses it for its own bookkeeping.

### Codex

To run Codex against them, create a dedicated Codex home with an `environments.toml` pointing at the sandbox (this example uses v86 on port 8686):

```bash
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

```

Log in once with that home, then launch Codex using it:

```bash
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"

```

`danger-full-access` tells Codex not to layer its own sandbox inside ours. Our automated tests pass against Codex CLI 0.164.0, using `codex exec` and a simulated model. Its exec-server protocol is experimental, so other versions may need checking.

### Pi

To run [Pi](https://pi.dev/?ref=blog.primeradiant.com) against them, load our [external-sandbox-pi](https://www.npmjs.com/package/external-sandbox-pi?ref=blog.primeradiant.com) extension with Pi's built-in tools disabled. Run this from the project directory the server was started in (this example uses Quicksand on port 8688):

```bash
pi -e npm:external-sandbox-pi --no-builtin-tools \
  --sandbox-url http://127.0.0.1:8688

```

`-e npm:` downloads the extension for that run only, and `--no-builtin-tools` means nothing can run on your own computer if the extension fails to load. The extension needs Pi 1.5 or later. Pi's status bar shows `Sandbox: ...` once it has connected.

## Controlling network access

By default, the three sandbox implementations do not have any external network access. This provides protection by default against bugs or prompt injection attacks that could leak private data to an external source, as described in [the lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/?ref=blog.primeradiant.com).

Each sandbox can be configured to allow HTTP and HTTPS network access via a proxy, with that proxy controlling which hosts can be accessed and the HTTP verbs that can be used with them. This can be used to allow read-only or full access to specific hosts.

When the proxy is enabled, `HTTP_PROXY` and `HTTPS_PROXY` environment variables are set in the sandbox so that clients like `wget` know how to access the network via the proxy. The sandbox also makes the proxy's CA certificate available, pointing variables such as `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE` and `NODE_EXTRA_CA_CERTS` at it, so that clients can access secure sites while allowing the proxy to inspect and filter their traffic. Code that ignores these settings and tries to connect directly is still blocked.

The `--proxy-config` option can be pointed at a file that specifies which hosts and which methods should be enabled for the session. Here's an example proxy configuration file:

```json
{
  "allow": [
    {
      "origin": "https://pypi.org",
      "methods": ["GET", "HEAD"]
    },
    {
      "origin": "https://files.pythonhosted.org",
      "methods": ["GET"]
    },
    {
      "origin": "https://api.github.com",
      "methods": ["GET"],
      "credential": {
        "header": "authorization",
        "placeholder": "Bearer placeholder-github-token",
        "secretEnv": "GITHUB_TOKEN",
        "prefix": "Bearer "
      }
    }
  ],
  "guestEnv": {
    "GITHUB_TOKEN": "placeholder-github-token"
  }
}

```

### Credential replacement for HTTP APIs

Credential replacement allows code running inside the sandbox to make authenticated calls to web APIs without the key itself being exposed to the agent or made available inside the sandbox.

The example above configures that for the GitHub API. Requests can be made via the proxy to `https://api.github.com/` with an authorization header of `Bearer placeholder-github-token`. The proxy will replace these headers with the value from the `GITHUB_TOKEN` environment variable in the environment of the sandbox server running on the host. The `guestEnv` block gives code inside the sandbox a `GITHUB_TOKEN` variable holding the placeholder.

This means agents can make authenticated calls to APIs without the API key being made visible to the agent itself. An allowed host could still echo a credential back in its response, so only use credential rules with services you trust, and keep their methods and paths narrow.

Running the sandbox like this will make the GitHub API token available to the proxy:

```bash
GITHUB_TOKEN="$(gh auth token)" npx --yes external-sandbox-v86 \
  --proxy-config proxy.json \
  --preserve-paths --mount-rw "project=$PWD"

```

### Monitoring the network and editing the policy

Here's a session in the sandbox web UI showing different requests being blocked or allowed based on the above example network configuration. `fetch.py` is a short script that makes one request and prints the result:

![The external-sandbox-v86 web terminal showing one allowed and two denied requests](https://storage.ghost.io/c/c2/33/c2337b7d-2a3a-4cb4-8e28-7d30596f7cd7/content/images/2026/11/sandbox-terminal.png)

The `/proxy` page of the sandbox web UI allows the network policy to be edited while the session is running, and also shows a log of recent requests allowed or denied by the proxy:

![The network policy page with allowed destinations, the policy JSON editor and recent proxy activity](https://storage.ghost.io/c/c2/33/c2337b7d-2a3a-4cb4-8e28-7d30596f7cd7/content/images/2026/11/sandbox-proxy.png)

The `/proxy` page is only available if the server was started with either the `--proxy` flag or by passing an initial configuration using `--proxy-config proxy.json`.

Refer to the [proxy section of the protocol specification](https://github.com/prime-radiant-inc/external-sandbox/blob/main/PROTOCOL.md?ref=blog.primeradiant.com#7-managed-https-proxy-p1p4) for the full policy format, which all three sandboxes share, and the [v86 proxy guide](https://github.com/prime-radiant-inc/external-sandbox-v86/blob/main/docs/proxy.md?ref=blog.primeradiant.com) for more examples.

## How each agent connects to a sandbox

Different coding agents provide different ways of ensuring all executed commands run in a custom environment.

### CLAUDE\_CODE\_SHELL\_PREFIX

Claude Code's mechanism for this is controlled by an environment variable. When `CLAUDE_CODE_SHELL_PREFIX` is set, Claude's Bash tool runs every command with that as a prefix, something like this:

```bash
claude-shell-prefix.sh 'uname -m; pwd; printf "hello from Linux\n"'

```

We can use this to take the intended commands and execute them any way we like, provided the execution environment can handle full shell strings (including environment variables, semicolons, etc.)

### codex exec-server

Codex has a `codex exec-server` mechanism, which allows Codex to talk to "a small JSON-RPC server for spawning and controlling subprocesses".

OpenAI provide their own implementation of this as part of Codex, but since Codex is open source it's possible to extract out the details and build a separate implementation of them.

This means we can point Codex at a server implementing that JSON-RPC spec and it can then control that other environment.

The `environments.toml` file shown in the Codex section above is what points Codex at that server. Its `url` is the sandbox's `/codex` WebSocket endpoint.

### Pi extensions

The [Pi coding agent](https://pi.dev/?ref=blog.primeradiant.com) allows extensions to replace Pi's default set of tools with custom versions. `external-sandbox-pi` replaces the `bash`, `read`, `write`, `edit`, `grep`, `find`, and `ls` tools with versions that act against the configured sandbox.

It also configures Pi's `!command` and `!!command` shortcuts to execute inside the sandbox. `!command` runs a command and adds its output to the conversation, while `!!command` runs it without sending the output to the model.

Running `pi -e npm:external-sandbox-pi --no-builtin-tools` ensures that Pi has no tools that run on your own computer, even if the extension fails to load. If the sandbox cannot be reached, the tools return an error rather than falling back to those defaults.

Run this command inside Pi to confirm that commands are being sent to your sandbox:

```
!uname -a

```

You should see Linux rather than Darwin. The rest of the output varies depending on which sandbox you are running.

You can configure Pi to always talk to the sandbox by installing the extension and setting an environment variable like this:

```bash
pi install npm:external-sandbox-pi
export EXTERNAL_SANDBOX_API_URL=http://127.0.0.1:8686

```

Put the `export` line in your shell profile to keep it across terminal sessions.

To remove the extension, run this:

```bash
pi remove npm:external-sandbox-pi

```

## Let us know what you think

These sandboxes should still be considered experimental prototypes: they are an effective demonstration of the external sandbox pattern, but they have not been audited to a level that you should trust them with sensitive workloads.

Two more limitations to keep in mind: A read-write mount still lets the agent damage anything in that folder, so keep it under version control and use read-only mounts where you can. And the sandboxes run Linux, so dependencies built for macOS - a `node_modules` or `.venv` folder in your project, for example - may need to be reinstalled inside the sandbox.

The combination of three different sandbox implementations with three different client agents shows that the protocol can be used to mix and match models, agents, and sandboxing platforms. If you want to build a sandbox on top of another technology, the [specification](https://github.com/prime-radiant-inc/external-sandbox/blob/main/PROTOCOL.md?ref=blog.primeradiant.com) and [conformance tool](https://github.com/prime-radiant-inc/external-sandbox?ref=blog.primeradiant.com) are the place to start.

If you try these out and have suggestions for improvements or find flaws in our design, please let us know with an issue on the [external-sandbox](https://github.com/prime-radiant-inc/external-sandbox?ref=blog.primeradiant.com) repo.