pi-guard-sandbox

[!IMPORTANT] Support for Destructive Command Guard has been added; you install, maintain, and upgrade DCG yourself.

[!NOTE] Two rounds of real-world testing — all passed. Routine bash, file I/O, and git operations feel seamless. Out-of-bounds writes, dangerous commands, and sensitive reads are blocked on contact.

---

中文文档

---

Platform: Linux / WSL. macOS may work but hasn't been tested. Windows is not supported.

Pi Guard is a high-agency, OS-level sandbox for Pi. Let your Agent work freely where it should, block it where it shouldn’t — with real boundary enforcement, interactive permission prompts, and no heavy workflow overhead.

• ⚙️ Fully controllable: configure protection mode, network, Sandbox, and DCG policy per project, then adjust them temporarily in the current Pi run
• 🧠 High-agency: full freedom inside the workspace, hard stops only at the boundary
• 🪶 Clean: minimal setup, intuitive config, low-friction daily use
• 🛡️ Hardened: bash runs in a real sandbox, not string-matching theater
• 🔍 Optional DCG support: use Destructive Command Guard for richer Bash command-risk decisions
• 🤝 Composable: coexists with pi-tool-display and other bash-overriding extensions
• 🎯 One package, done: no need to stitch together a stack of guardrail tools

---

Changelog

• 0.2.4 — Added optional Destructive Command Guard (DCG) integration, runtime Guard/Sandbox/DCG switches, /guard argument completion, and Footer status.
• 0.2.1 — Sandbox now inherits host environment variables and uses the real HOME. Fixes tools that read config files or API keys from ~/. paths (e.g. Tavily).
• 0.2.0 — Network toggle: /guard non / /guard noff to allow or block all outbound network. Default open. Footer shows · network: open|blocked.
• 0.1.0 — Initial release: write-boundary protection, read-only / workspace-write modes, sandboxed bash, dangerous command blocking.

---

1. Installation

System dependencies

Tool	Purpose	Install
bwrap	Linux process sandbox	sudo apt install bubblewrap
socat	Sandbox network proxy	sudo apt install socat
rg	File scanning	sudo apt install ripgrep

Install the extension

From npm

pi install npm:pi-guard-sandbox      # global — all projects

pi install -l npm:pi-guard-sandbox   # project-local only

After installation, enter your project and run /guard i to initialize.

From this repo

If you've cloned this repository, the development extension is at extensions/pi-guard/. It is deliberately not under .pi/extensions/, so Pi started from the repository root does not auto-load development code:

cd extensions/pi-guard && npm install

Test it explicitly with Pi's extension flag, then run /guard init. Installed packages still use Pi's normal package/discovery paths (for example ~/.pi/agent/extensions/ or the package location chosen by pi install).

For a global install from this repo: copy extensions/pi-guard/ to ~/.pi/agent/extensions/pi-guard/ and run npm install there.

---

2. What Guard leaves in your project

Know what you're getting into.

Item	Description
.pi/pi-guard.json	Created on init — all Guard configuration
footer status line	Persistent mode indicator at the bottom of Pi
sandboxed bash	All Agent bash commands run in a sandbox, not directly on the host
vendor/ directory	~1.8 MB — sandbox runtime (forked from @anthropic-ai/sandbox-runtime)
extensions/pi-guard/	This repository's development source; it is not an auto-discovery path

Delete .pi/pi-guard.json and run /reload to disable Guard.

---

3. Quick start

Start Pi in your project directory:

/guard init              → initialize — creates config
/guard read-only         → temporary read-only mode
/guard sandbox off       → temporarily remove OS sandbox wrapping
/guard dcg off           → temporarily use the built-in Bash policy

Guard takes effect immediately after initialization. The footer shows the current mode.

---

4. Command reference

Command	Shortcut	Purpose
/guard status	—	Show complete runtime status and configuration
/guard init	/guard i	Create .pi/pi-guard.json and enable Guard
/guard on / /guard off	—	Enable/disable all Guard enforcement for this Pi run
/guard sandbox on / off	—	Enable/disable only OS sandbox wrapping for this Pi run
/guard dcg on / off	—	Enable/disable optional DCG policy for this Pi run
/guard read-only	/guard r	Switch to read-only
/guard workspace-write	/guard w	Switch to workspace-write
/guard network on	/guard non	Allow all outbound network (default)
/guard network off	/guard noff	Block all outbound network

All slash-command changes are runtime overrides: they never rewrite .pi/pi-guard.json, and a new Pi run restores project defaults. /guard <Tab> offers the canonical commands. /guard status lists the active overrides; the compact footer shows states such as [Guard: workspace-write · DCG], [Guard: sandbox-off · built-in], and [Guard: OFF].

Turning the sandbox off leaves the path policies and Bash policy active, but Agent Bash has normal host filesystem and network permissions. Turning Guard off disables all of them until the user runs /guard on.

Note: Even with network open, ping (ICMP) is unavailable inside the sandbox. Bubblewrap drops CAP_NET_RAW by default. HTTP/HTTPS (curl, wget, git, etc.) work normally.

---

5. Mode comparison

	read-only	workspace-write
Read inside workspace	✅	✅
Read outside workspace	✅ (sensitive paths excluded)	✅ (sensitive paths excluded)
Write inside workspace	❌	✅
Write outside workspace	❌	❌ (requires approval)
Bash commands	✅ (no persistent writes)	✅ (workspace + /tmp writable)
Bash writes outside workspace	❌	❌
Dangerous commands	blocked + approval	blocked + approval

Sensitive paths (unreadable)

~/.ssh ~/.aws ~/.gnupg ~/.git-credentials ~/.npmrc ~/.pypirc ~/.netrc ~/.env ~/.env.*

What Guard does NOT protect

User-typed !cmd / !!cmd are not guarded. Guard only covers Agent-initiated tool calls.

---

6. Optional DCG policy engine (TUI only)

Pi Guard operates only when ctx.mode === "tui". In print, JSON, RPC, and other non-TUI modes it does not initialize the sandbox, invoke DCG, intercept tools, or render UI.

Destructive Command Guard (DCG) is an optional external Bash policy engine, not a sandbox and not an npm dependency. Install and upgrade it yourself, then verify it in the environment that starts Pi:

dcg --version

Pi Guard automatically uses dcg --robot test "<command>" when DCG is enabled and available. Set DCG_BIN=/path/to/dcg when it is not on PATH. A genuinely missing executable falls back quietly to bashPolicy; a timed-out, signaled, or otherwise failed availability check is shown as DCG:error and follows onError. A DCG process timeout is bounded to one second plus a short termination grace period, so an optional integration cannot wait forever. A malformed, timed-out, or failed DCG call never falls through to the built-in policy for that same command: its onError action applies instead.

DCG only sees Agent calls to the standard bash tool. It does not guard !cmd, !!cmd, custom shell tools, or scan arbitrary bash script.sh file contents. The OS sandbox remains the hard filesystem/network boundary.

7. Troubleshooting

Status	Cause	Action
Guard: uninitialized	Not yet initialized	Run /guard i
Guard: invalid-config	JSON syntax error	Fix .pi/pi-guard.json, then /reload
Guard: sandbox-unavailable	Missing system deps or npm install skipped	Follow Section 1 — check bwrap, socat, rg

---

8. Configuration: .pi/pi-guard.json

/guard init generates this file. You can edit it by hand (requires /reload to take effect).

Full example

{
  "enabled": true,
  "sandbox": { "enabled": true },
  "mode": "workspace-write",
  "network": "open",
  "dcg": {
    "enabled": true,
    "onDeny": "confirm",
    "onIndeterminate": "notify",
    "onError": "notify"
  },

  "sensitiveReadDeny": [
    "~/.ssh",
    "~/.aws",
    "~/.npmrc"
  ],

  "protectedPaths": {
    "block": [
      ".git",
      "node_modules"
    ],
    "approval": [
      ".env",
      ".env.*",
      ".pi/pi-guard.json"
    ]
  },

  "bashPolicy": {
    "directBlock": [
      "sudo",
      "su",
      "dd"
    ],
    "requireApproval": [
      "rm-rf",
      "git-reset-hard",
      "git-clean-fd"
    ]
  }
}

Field reference

Field	Description
enabled	Project startup default for the Guard master switch
sandbox.enabled	Project startup default for OS sandbox wrapping
mode	"readonly" or "workspace-write". Switch with /guard r / /guard w
network	"open" (outbound allowed) or "blocked" (all outbound denied). Switch with /guard non / /guard noff
dcg.enabled	Use DCG automatically when its binary is available
dcg.onDeny, dcg.onIndeterminate, dcg.onError	One of "allow", "notify", "confirm", or "block"; defaults are confirm, notify, and notify
sensitiveReadDeny	Paths blocked from all Agent reads. Supports ~ and globs
protectedPaths.block	Paths where write / edit are rejected outright
protectedPaths.approval	Paths where write / edit trigger an approval prompt
bashPolicy.directBlock	Bash commands rejected immediately
bashPolicy.requireApproval	Bash commands requiring approval

Adding your own sensitive paths

"sensitiveReadDeny": [
  "~/.ssh",
  "~/.aws",
  "~/my-project/secrets.yml"
]

Adding custom dangerous commands

"bashPolicy": {
  "directBlock": [
    "sudo",
    "docker-host-root-bind"
  ],
  "requireApproval": [
    "rm-rf",
    "bash-c"
  ]
}

Entries in bashPolicy are policy IDs, not raw regex. See the default config generated by init for the full list.