[!TIP] 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.

• 🧠 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
• 🤝 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.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 extension is already at .pi/extensions/pi-guard/:

cd .pi/extensions/pi-guard && npm install

Start Pi, then run /guard i.

For a global install from this repo: copy .pi/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) | | .pi/extensions/pi-guard/ | The extension code itself |

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

3. Quick start

Start Pi in your project directory:

/guard i        → initialize — creates config
/guard r        → switch to read-only mode
/guard w        → switch to workspace-write (default)

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

4. Command reference

| Command | Shortcut | Purpose | |---------|----------|---------| | /guard | — | Show status and configuration | | /guard init | /guard i | Create .pi/pi-guard.json and enable Guard | | /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 |

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. 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 |

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

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

Full example

{
  "mode": "workspace-write",
  "network": "open",

  "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 | |-------|-------------| | 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 | | 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.