{"id":50055974,"url":"https://github.com/code-yeongyu/pi-sandbox","last_synced_at":"2026-05-21T13:14:07.030Z","repository":{"id":355023917,"uuid":"1226459907","full_name":"code-yeongyu/pi-sandbox","owner":"code-yeongyu","description":"Policy-aware sandbox extension for pi-mono with native, Docker, justbash, QEMU, and SSH backends","archived":false,"fork":false,"pushed_at":"2026-05-18T07:19:26.000Z","size":1056,"stargazers_count":1,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T09:36:31.818Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/code-yeongyu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-01T12:31:03.000Z","updated_at":"2026-05-18T07:19:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/code-yeongyu/pi-sandbox","commit_stats":null,"previous_names":["code-yeongyu/pi-sandbox"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/code-yeongyu/pi-sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-yeongyu%2Fpi-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-yeongyu%2Fpi-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-yeongyu%2Fpi-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-yeongyu%2Fpi-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/code-yeongyu","download_url":"https://codeload.github.com/code-yeongyu/pi-sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-yeongyu%2Fpi-sandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33301811,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"ssl_error","status_checked_at":"2026-05-21T12:22:11.673Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-21T13:14:06.047Z","updated_at":"2026-05-21T13:14:07.023Z","avatar_url":"https://github.com/code-yeongyu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-sandbox\n\n[![ci](https://github.com/code-yeongyu/pi-sandbox/actions/workflows/ci.yml/badge.svg)](https://github.com/code-yeongyu/pi-sandbox/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/pi-sandbox.svg)](https://www.npmjs.com/package/pi-sandbox)\n[![license](https://img.shields.io/npm/l/pi-sandbox.svg)](https://github.com/code-yeongyu/pi-sandbox/blob/main/LICENSE)\n\nPolicy-aware sandboxing extension for [pi-mono](https://github.com/mariozechner/pi-mono) that intercepts `bash`, `read`, `write`, and `edit` tool operations and enforces per-project sandbox policy across native, Docker, justbash, and QEMU sandbox backends. SSH is a remote transport profile with file facets and env scrub semantics.\n\n## Quick start\n\n```bash\n# 1. Install the extension\nnpm install pi-sandbox\n\n# 2. Create a project policy\nmkdir -p .pi \u0026\u0026 cat \u003e .pi/sandbox.jsonc \u003c\u003c'EOF'\n{\n\t\"backend\": { \"kind\": \"docker\", \"image\": \"node:22-alpine\" },\n\t\"network\": { \"mode\": \"deny\" },\n\t\"file\": {\n\t\t\"defaultRead\": \"allow\",\n\t\t\"defaultWrite\": \"deny\",\n\t\t\"roots\": [{ \"path\": \".\", \"read\": true, \"write\": true }]\n\t}\n}\nEOF\n\n# 3. Load into pi\npi -e ./node_modules/pi-sandbox/src/index.ts\n```\n\n## Feature matrix\n\n| Control | justbash | docker | native (darwin) | native (linux) | qemu | ssh transport |\n|---------|:--------:|:------:|:---------------:|:--------------:|:----:|:-------------:|\n| fileRead | host-root | bind mount | host-root | host-root | shared root | remoteRoot |\n| fileWrite | host-root | bind mount | host-root | host-root | share mode | remoteRoot |\n| fsPathResolution | mount-boundary | mount-boundary | realpath+toctou | mount-boundary | mount-boundary | mount-boundary |\n| networkDeny | virtual shell | network none | sandbox-exec | bwrap | network none | transport only |\n| restricted network | config error | config error | config error | config error | config error | config error |\n| processIsolation | virtual shell | container | seatbelt policy | bwrap | VM | transport only |\n| envScrub | local | container | local | local | guest | remote |\n| stdoutCapture | streaming | streaming | streaming | streaming | streaming | streaming |\n| pathMapping | host-root | bind mount | identity | identity | shared root | remoteRoot |\n| persistence | ephemeral | ephemeral | yes | yes | ephemeral | remoteRoot lifecycle |\n| denialAttribution | structured | structured | structured | structured | structured | generic |\n\nSee [docs/BACKENDS.md](docs/BACKENDS.md) for per-backend capability tables, probe semantics, and operational limits.\n\n## Configuration\n\nPolicy lives in JSONC files:\n\n- `.pi/sandbox.jsonc` — project policy\n- `~/.pi/sandbox.json` — global user policy (lower precedence)\n- `.pi/sandbox.grants.jsonc` — project approval grants\n- `~/.pi/sandbox.grants.jsonc` — global approval grants\n\nSee [docs/CONFIG.md](docs/CONFIG.md) for the full schema, merge semantics, hash bindings, and annotated examples.\n\nCI release gates can require one backend smoke with `npm run test:live-required`; it sets `PI_SANDBOX_REQUIRE_LIVE=1` and fails if the live smoke cannot execute.\n\n## TUI and slash commands\n\nThe extension registers a TUI footer and widget showing the active backend, control states, and recent blocks. Five slash commands are available:\n\n| Command | Description |\n|---------|-------------|\n| `/sandbox` | Help and status summary |\n| `/sandbox-status` | Full status with policy hashes and approvals |\n| `/sandbox-switch \u003cbackend\u003e` | Validate a backend kind switch |\n| `/sandbox-allow \u003cclass\u003e \u003ctarget\u003e` | Persist a typed allow grant |\n| `/sandbox-deny \u003cclass\u003e \u003ctarget\u003e` | Persist a typed deny grant |\n\nSee [docs/SECURITY.md](docs/SECURITY.md) for the threat model, block codes, and approval flow.\n\n## Architecture\n\n```\n+--------------------------------------------------+\n|  pi-mono session                                  |\n|  +---------------------------------------------+  |\n|  |  pi-sandbox extension                        |  |\n|  |  +----------------+  +--------------------+  |  |\n|  |  | SandboxManager |-\u003e| SandboxBackend     |  |  |\n|  |  |  - decide()    |  |  - bash.exec()     |  |  |\n|  |  |  - run()       |  |  - lifecycle       |  |  |\n|  |  +----------------+  +--------------------+  |  |\n|  |         ^                ^                  |  |\n|  |         |                |                  |  |\n|  |  +----------------+  +--------------------+  |  |\n|  |  | EffectivePolicy|  | PathMapper         |  |  |\n|  |  |  - backend     |  |  - hostToSandbox   |  |  |\n|  |  |  - file        |  |  - sandboxToHost   |  |  |\n|  |  |  - network     |  +--------------------+  |  |\n|  |  +----------------+                         |  |\n|  |         ^                                    |  |\n|  |         |                                    |  |\n|  |  +----------------+  +--------------------+  |  |\n|  |  | ConfigLoader   |  | ApprovalStore      |  |  |\n|  |  |  - merge       |  |  - typed grants    |  |  |\n|  |  |  - normalize   |  +--------------------+  |  |\n|  |  +----------------+                         |  |\n|  +---------------------------------------------+  |\n+--------------------------------------------------+\n```\n\n## Documentation\n\n- [docs/BACKENDS.md](docs/BACKENDS.md) — backend reference\n- [docs/CONFIG.md](docs/CONFIG.md) — configuration reference\n- [docs/SECURITY.md](docs/SECURITY.md) — security model and threat model\n- [CHANGELOG.md](CHANGELOG.md) — release history\n\n## License\n\nMIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).\n\n## Related\n\n- [senpi](https://github.com/code-yeongyu/senpi) — the fork/runtime these extensions are extracted from.\n- [Ultraworkers Discord](https://discord.gg/PUwSMR9XNk) — community link from the senpi README.\n- [Dori](https://sisyphuslabs.ai) — the product powered by senpi under the hood.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-yeongyu%2Fpi-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcode-yeongyu%2Fpi-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-yeongyu%2Fpi-sandbox/lists"}