pi-docker-sandbox

Lightweight Docker sandbox for the pi coding agent.

Default: complete isolation. No network, no host filesystem. The agent runs in an empty container with Chromium, Playwright, Node 22, git, and essential CLI tools.

Quick start

# Install the extension
pi install npm:pi-docker-sandbox

# Build the sandbox image (once)
docker build -t agent-sandbox:latest .

# Start pi — sandbox is on by default
pi

Flags

Flag	Default	Purpose
--no-sandbox	—	Disable sandbox entirely
--sandbox-network	off	Allow outbound network (enables browser tool)
--sandbox-mount-cwd	off	Mount the project at /workspace (rw)
--sandbox-mount-skills	off	Mount agent skill directories at /skills (ro)
--sandbox-mount-ssh	off	Forward $SSH_AUTH_SOCK for git over SSH
--sandbox-memory	4g	Memory limit
--sandbox-cpus	2	CPU limit
--sandbox-name	auto	Reusable container name

Commands

Command	Purpose
/sandbox	Show container status, flags, and resource usage
/sandbox doctor	Verify tools inside the container
/sandbox stop	Stop the sandbox container
/sandbox restart	Restart the sandbox container
/sandbox rebuild	Rebuild the sandbox Docker image
/sandbox prune	Remove all stopped pi-agent-* containers
/sandbox network on|off	Toggle outbound network access
/sandbox ssh on|off	Toggle SSH agent forwarding
/sandbox cwd on|off	Toggle project CWD mount
/sandbox skills on|off	Toggle skill directory mounts

Toggles (network, ssh, cwd, skills) persist across reloads and require a container restart to take effect.

Architecture

pi starts
  └─ session_start → SandboxManager.start()
       ├─ docker run agent-sandbox:latest
       ├─ Proxy read/write/edit/bash via docker exec
       ├─ Inject system prompt with sandbox state
       └─ Register cleanup on SIGINT/SIGTERM/exit
  └─ session_shutdown → SandboxManager.stop()

Module structure

Module	Responsibility
types.ts	Interfaces: DockerClient, FileStore, SandboxHandle, UIContext, …
docker.ts	Docker CLI abstraction (q, createRealDockerClient, stopSync)
path-translation.ts	toRemote() — host→container path mapping
prompt.ts	buildSystemPrompt() — sandbox status for agent system prompt
toggles.ts	ToggleStore — persisted feature toggles (survives ctx.reload())
sandbox.ts	SandboxManager — container lifecycle, exec, path translation
tools.ts	createReadOps, createWriteOps, createBashOps — tool adapters
commands.ts	/sandbox subcommand routing (handleSandboxCommand)
index.ts	Extension entry point — flags, tool registration, event wiring

Image contents

• Chromium (system package) + Playwright (preconfigured, no browser download)
• Node 22 LTS (from node:22-bookworm-slim)
• git, curl, jq, ripgrep, fd, openssh-client
• Non-root node user (uid 1000)

Companion extensions

For a complete web research setup, pair this sandbox with:

• pi-webai — web browsing and AI-powered extraction
• pi-textbrowser — lightweight text-mode browser
• pi-smart-fetch — intelligent content fetching

All three run inside the sandbox when network is enabled (--sandbox-network).

Development

# Install dependencies
npm install

# Run tests
npm test

# Type check
npx tsc --noEmit