pi-sandbox

Capability-aware filesystem, process, and network sandboxing for pi coding agent. Shell processes run inside Anthropic's Sandbox Runtime, while pi's tool_call event gates tools executed in the pi process. Tools without a declared capability are denied by default.

Quick start

npm install
npm run build
pi --extension ./src/index.ts --sandbox r       # workspace read-only
pi --extension ./src/index.ts --sandbox w       # workspace writable (default)
pi --extension ./src/index.ts --sandbox yolo    # explicitly disable sandboxing

Use /sandbox inside pi to inspect the effective policy, and /sandbox <r|w|yolo> to switch the running session's level (with tab completion for the level names). Level r permits workspace reads, w also permits workspace writes, and yolo disables restrictions.

Switching rebuilds the policy and restarts the OS sandbox runtime in place; the tool gate, the status bar, and the exported PI_SANDBOX_LEVEL follow immediately. A session that inherited PI_SANDBOX_LEVEL from its parent can only switch within that ceiling (strictest(requested, inherited)), so runtime switching preserves the rule that delegation can never widen a sandbox. If the runtime refuses the new level, the previous level is restored and /sandbox reports the failure.

Flexible permission configuration

Permissions are declared per tool, including orchestration tools such as subagent. You can change the policy in ~/.pi/agent/extensions/sandbox.json or a project-local .pi/sandbox.json without changing extension code.

Supported capabilities are filesystem.read, filesystem.write, process.execute, and network.connect:

{
  "tools": {
    "subagent": { "capabilities": [] },
    "web_search": { "capabilities": ["network.connect"] },
    "file_editor": {
      "capabilities": ["filesystem.read", "filesystem.write"]
    }
  }
}

An empty capability list marks a tool as orchestration only. This is useful for subagent, task scheduling, and coordination tools. Resource operations performed inside a child session are still checked by that session's own policy engine, so delegation cannot bypass sandbox checks.

Combine tool declarations with path and network rules:

{
  "level": "r",
  "unknownTools": "deny",
  "network": { "allowedDomains": ["api.example.com"] },
  "filesystem": { "allowRead": ["./fixtures"] },
  "tools": {
    "subagent": { "capabilities": [] },
    "my_search": { "capabilities": ["network.connect"] }
  }
}

The global configuration and project configuration are merged, with project values taking precedence. PI_SANDBOX_LEVEL provides an inherited ceiling: child sessions can tighten permissions, but can never widen the effective level of their parent.

Extension authors can declare capabilities in code:

declareSandboxTool("my_tool", { capabilities: ["filesystem.read"] });

Development

npm run check   # typecheck and tests
npm run build   # emit dist/

The integration entry point is src/integration/extension.ts; policy, configuration loading, and capability registration live under src/policy, src/config, and src/capabilities.

License

MIT