# pi-sandbox

### Install with `pi install npm:@foxfirecodes/pi-sandbox`!

Sandbox for [pi](https://pi.dev/).

Sandboxes pi like this:

- read/write/edit: direct control using allow/deny lists
- bash: uses [`@foxfirecodes/sandbox-runtime`](https://www.npmjs.com/package/@foxfirecodes/sandbox-runtime) to control network and file system access

When a blocked action is attempted, the user is
prompted to allow it temporarily or permanently rather than silently failing.

![demo](./demo/demo.gif)

## Notes

There is an example config at [sandbox.json](./sandbox.json). It was quite a few things added to get this extension to work with [agent-browser](https://agent-browser.dev/) and other common tools.

These open significant security loopholes, so shouldn't be used in a sensitive context or when you don't need browser support.

You may need to trial and error to find additional things you need to allow.

## Quickstart

#### Prerequisites

`pi-sandbox` delegates the OS-level bash sandbox to
[`@foxfirecodes/sandbox-runtime`](https://www.npmjs.com/package/@foxfirecodes/sandbox-runtime),
published from a fork of Anthropic's
[`anthropic-experimental/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime).
The sandbox runtime checks for [`ripgrep`](https://github.com/BurntSushi/ripgrep) (the
`rg` binary) on **both macOS and Linux** at sandbox-init time. If `rg`
is not on the `PATH` that pi was launched with, sandbox initialization
fails with:

```
Sandbox initialization failed: Sandbox dependencies not available: ripgrep (rg) not found
```

Install ripgrep before enabling the extension:

| Platform              | Install                                              |
| --------------------- | ---------------------------------------------------- |
| macOS (Homebrew)      | `brew install ripgrep`                               |
| macOS (MacPorts)      | `sudo port install ripgrep`                          |
| Linux (Debian/Ubuntu) | `sudo apt install ripgrep`                           |
| Linux (Fedora/RHEL)   | `sudo dnf install ripgrep`                           |
| Linux (Arch)          | `sudo pacman -S ripgrep`                             |
| From source / other   | <https://github.com/BurntSushi/ripgrep#installation> |

If `which rg` succeeds in your shell but pi still reports `rg not
found`, pi is being launched from a parent process whose `PATH` does
not include the directory containing `rg` (common when GUI launchers
inherit a minimal non-login `PATH`). On macOS, `/opt/homebrew/bin` and
`/usr/local/bin` are the usual culprits — make sure your launcher's
environment includes whichever one your install uses.

#### Install

```bash
pi install npm:pi-sandbox
```

#### Configure

Add a config like this either to `~/.pi/agent/sandbox.json` (global) or to `.pi/sandbox.json` (local).
Local config takes precedence over global.

Note below that the order of precedence for filesystem read and write are opposite.

```json
{
  "enabled": true,
  "allowBrowserProcess": true, // If you want to use agent-browser or similar Chrome setup
  "commandPatterns": {
    // Bash/! commands matching allowPatterns bypass the sandbox entirely.
    // Bash/! commands matching denyPatterns are hard-blocked.
    // Non-regex entries are shell-style globs matched against the whole command.
    // re:/pattern/flags entries are JavaScript regexes.
    // denyPatterns take precedence over allowPatterns.
    "allowPatterns": ["gh auth status"],
    "denyPatterns": []
  },
  "network": {
    "allowLocalBinding": true, // ditto
    "allowAllUnixSockets": true, // ditto
    "allowedDomains": ["github.com", "*.github.com"],
    "deniedDomains": []
  },
  "filesystem": {
    // For READS:
    // - ANY read is prompted unless the path is already in allowRead
    // - Granting a prompt adds to allowRead, which overrides denyRead
    // - denyRead is not a hard-block; it just marks regions as denied by default
    "denyRead": ["/Users", "/home"],
    "allowRead": [".", "~/.config", "~/.local", "Library"],

    // For WRITES:
    // - empty ALLOW means no write access at all
    // - DENY takes precedence and is never prompted
    "allowWrite": [".", "/tmp"],
    "denyWrite": [".env", ".env.*", "*.pem", "*.key"]
  }
}
```

#### Usage

```
pi --no-sandbox          disable sandboxing for the session
/sandbox                 show current configuration and session allowances
```

## What it does

**Bash commands** are wrapped with `sandbox-exec` (macOS) or `bubblewrap`
(Linux) to enforce network and filesystem restrictions at the OS level.
Commands matching `commandPatterns.allowPatterns` bypass this entirely: no OS
sandbox wrapper, no network pre-check, and no write-block retry prompt.
Commands matching `commandPatterns.denyPatterns` are hard-blocked before
execution. Deny patterns take precedence over allow patterns.

**Read, write, and edit tool calls** are intercepted before execution and
checked against the same filesystem policy. The OS-level sandbox cannot cover
these tools because they run directly in the Node.js process rather than in a
subprocess.

When a block is triggered, a prompt appears with four options:

- Abort (keep blocked)
- Allow for this session only
- Allow for this project — written to `.pi/sandbox.json`
- Allow for all projects — written to `~/.pi/agent/sandbox.json`

**Session allowances** are held in memory only. They are never written to disk
and the agent has no way to read or modify them. They are reset when the
extension reloads or pi restarts.

### What is prompted vs. hard-blocked

| Rule                                            | Behaviour                                           |
| ----------------------------------------------- | --------------------------------------------------- |
| Command matches `commandPatterns.denyPatterns`  | Hard-blocked, no prompt (bash and `!cmd`)           |
| Command matches `commandPatterns.allowPatterns` | Sandbox bypassed entirely (bash and `!cmd`)         |
| Domain not in `allowedDomains`                  | Prompted (bash and `!cmd`)                          |
| Path not in `allowRead`                         | Prompted (read tool); granting adds to `allowRead`  |
| Path not in `allowWrite`                        | Prompted (write/edit tools and bash write failures) |
| Path in `denyWrite`                             | Hard-blocked, no prompt                             |
| Domain in `deniedDomains`                       | Hard-blocked at OS level, no prompt                 |

If a path is added to `allowWrite` via a prompt but is also present in
`denyWrite`, it remains blocked. A warning is shown explaining which config
files to check.

`commandPatterns.allowPatterns` and `commandPatterns.denyPatterns` support
shell-style `*` and `?` globs matched against the whole command after trimming
leading/trailing whitespace. Entries of the form `re:/pattern/flags` are treated
as JavaScript regexes. A pattern of `"*"` in `allowPatterns` bypasses sandboxing
for every bash/`!cmd` command; a pattern of `"*"` in `denyPatterns` blocks every
bash/`!cmd` command. pi-sandbox shows a warning when either is configured. Keep
allow patterns narrow: if an allow pattern matches a compound shell command such
as `cmd && other-cmd`, the entire command runs unsandboxed.

`allowedDomains` supports `*.example.com` wildcards. It also supports `"*"` to
allow all domains; pi-sandbox shows a warning when this is configured because it
removes per-domain prompts and can be easy to add accidentally. `allowWrite` uses prefix
matching, so `.` covers the entire current working directory.

On Linux, broad read allowances can coexist with more-specific nested write
allowances under the same directory. For example, `allowRead: ["~/.cache"]` with
`allowWrite: ["~/.cache/uv", "~/.cache/mise"]` exposes the cache tree read-only
while restoring the selected subtrees writable afterward. `denyWrite` and the
runtime's mandatory sensitive-path write denies are still applied last, so they
continue to override both broad reads and nested writes.

> **⚠️ Read and write have different precedence rules:**
>
> - **Read:** Every read is prompted unless the path is already in `allowRead`.
>   `denyRead` is not a hard-block — it marks regions as denied by default, but
>   granting a prompt adds the path to `allowRead`, overriding `denyRead`.
> - **Write:** `denyWrite` takes precedence over `allowWrite` and is never
>   prompted. A path in `denyWrite` is always blocked, even if it matches
>   `allowWrite`.

If neither file exists, built-in defaults apply (see above for the defaults).

The footer shows a lock indicator while the sandbox is active.

## Ackowledgements

Based on code from
[badlogic/pi-mono](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/examples/extensions/sandbox/index.ts)
by Mario Zechner, used under the
[MIT License](https://github.com/badlogic/pi-mono/blob/main/LICENSE).