@stixxert/pi-docker-sandbox 0.1.0 → 1.1.0

package/README.md

@@ -4,6 +4,15 @@ A [pi](https://pi.dev) extension that gives an AI coding agent a **private
 docker sandbox** to deploy into — powered by
 [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) (`sbx`).
 
+**How this sandboxes pi.** There are many ways to sandbox pi: wrap the whole
+agent in a container or dedicated VM, confine it in a locked-down workspace,
+or — as this project does — give pi a sandbox *to deploy into*. This is a
+**pi extension, not a wrapper**: pi itself is never contained. It keeps
+running in its normal host environment with its usual tools, workspace, and
+agent micro-VM; the extension only adds a separate private microVM — with its
+own docker daemon — as the agent's deploy target. What gets sandboxed here is
+the docker work, not the pi process.
+
 Each pi session gets its own **sandbox microVM with its own docker daemon**,
 running in parallel to the agent. The agent can pull images, build, run
 containers, and `docker compose up` — while the **host's docker is never
@@ -23,6 +32,42 @@ daemon are a liability. With this extension:
   redirect it.
 - `docker_verify` runs a live isolation audit (PASS/FAIL per check).
 
+## Two modes
+
+**1. Deploy target (default).** `pi install` this package and the agent gets
+the `docker_*` tools: a private sbx microVM, with its own daemon, to deploy
+into. pi's own tools keep running wherever pi runs.
+
+**2. Execution backend.** Load `sandbox/` instead and pi runs *against* the
+sandbox: `bash`, `read`, `write`, `edit`, `grep`, `find`, `ls` and your `!`
+commands all execute inside the sbx microVM, while pi itself stays on the
+host with its own auth, config, sessions and model keys.
+
+```bash
+cd /path/to/project
+pi -e /path/to/pi-docker-sandbox/sandbox
+```
+
+This is pi's "route tool execution into an isolated environment" pattern —
+the same shape as pi's [Gondolin
+example](https://github.com/earendil-works/pi-mono), with an sbx microVM as
+the target rather than a local QEMU VM. See [sandbox/README.md](sandbox/README.md).
+
+It is also the **lighter alternative to running pi inside a sandbox**: no
+template with pi baked in, no bootstrap seeding state into the sandbox, no
+per-project auth/sessions/credential handling, no sandbox rebuild to pick up
+a new pi version. The tools are *overridden*, not added — so the model's
+tool list is byte-for-byte the built-in one and not one prompt token is
+spent on the sandbox.
+
+The sandbox it creates can itself be slim: [template/](template/) builds a
+**648 MB** baseline automatically (vs ~2.2 GB for the pi-bearing template),
+because pi no longer has to live inside it. See
+[template/README.md](template/README.md).
+
+Both modes can be active at once; the `docker_*` tools keep working when the
+backend is loaded.
+
 ## Requirements
 
 - [pi](https://pi.dev) (the extension runs in the host pi process)
@@ -105,7 +150,7 @@ workspace mounted). No manual steps required.
 | `docker_init` | Scaffold a Dockerfile (+ compose) with language detection |
 | `docker_compose` | Deploy/manage compose projects (`up -d --build`) |
 | `docker_stop` / `docker_start` / `docker_rm` | Container lifecycle |
-| `docker_curl` | Probe a published port from the host process (GET/POST/PUT) |
+| `docker_curl` | Probe a published port from the host process (GET/POST/PUT; only ports this sandbox published) |
 | `docker_sandbox_rm` | Remove this session's sandbox (microVM + everything inside) |
 | `docker_gc` | Sweep stale `pi-sbx-*` sandboxes left by crashed sessions |
 
@@ -164,7 +209,8 @@ persistent name (e.g. a shared sandbox reused across restarts), pin
   mappings; after a host reboot let the session-start GC handle it, or run
   `sbx rm --force $(sbx ls -q | grep pi-sbx)` from a host pane.
 - Agent-side verification: `docker_curl` (host-side fetch, GET/POST/PUT with
-  optional body); human-side: `http://localhost:<hostport>/`.
+  optional body, confined to ports this sandbox published); human-side:
+  `http://localhost:<hostport>/`.
 
 See [boundary.md](boundary.md) for the full agent ↔ sbx boundary
 model and usage guide (agent + human). The extension is not dependent on
@@ -204,6 +250,11 @@ The agent's VM mounts the workspace at `/workspace`; the extension maps
 sandbox (the workspace is direct-mounted there). So `docker_build` contexts
 and `docker_run` volume binds "just work".
 
+The mapping is **confined to the workspace**: `/workspace/..` traversal,
+absolute host paths, and symlinks that point outside the workspace are all
+rejected, so the agent cannot reach host paths outside the mounted workspace
+via build contexts, volume binds, or `docker_init`.
+
 ## Example deploy flow
 
 ```
@@ -266,6 +317,35 @@ directly by pi (copy it to `~/.pi/agent/extensions/docker-sandbox.ts`, or
 pi package manifest (`pi.extensions`) and declares typecheck-only dev deps;
 `tsconfig.json` keeps `tsc --strict` honest against the pi SDK types.
 
+## Releases (CI/CD)
+
+Releases are fully automated with [semantic-release](https://semantic-release.gitbook.io/)
+via GitHub Actions (`.github/workflows/release.yml`). The **commit messages
+themselves signal the release**: push to `main` and CI analyzes commits since
+the last release tag, then bumps the version, tags, creates a GitHub Release,
+and publishes to npm — only when there is something releasable.
+
+| Commit message | Version bump |
+|---|---|
+| `fix: ...` | patch (`1.0.0` → `1.0.1`) |
+| `feat: ...` | minor (`1.0.0` → `1.1.0`) |
+| `BREAKING CHANGE: ...` (in body or footer) | major (`1.0.0` → `2.0.0`) |
+| anything else (`docs:`, `chore:`, `refactor:`, …) | no release |
+
+One-time setup: configure **trusted publishing** on npm so the workflow can
+publish via OIDC — no npm token stored anywhere. On npmjs.com → package
+`@stixxert/pi-docker-sandbox` → Settings → **Trusted Publisher**, add:
+
+- Organization or user: `stixxert`
+- Repository: `pi-docker-sandbox`
+- Workflow filename: `release.yml`
+- Environment name: *(leave empty)*
+- Allowed actions: `npm publish`
+
+`GITHUB_TOKEN` needs no setup. The first push to `main` containing a
+`fix:`/`feat:` commit publishes the initial version. Provenance attestations
+are generated automatically with trusted publishing.
+
 ## License
 
 Apache-2.0 — see [LICENSE](LICENSE).

package/boundary.md

@@ -14,6 +14,16 @@ for the **agent** and for the **human operator**.
 > Gondolin is used throughout this document simply as the concrete reference
 > deployment.
 
+> **Two modes.** This document describes the default **deploy target** mode,
+> where the sandbox exists for `docker_*` and the agent keeps using its own
+> tools. The repo also ships an **execution backend** (`sandbox/`) that routes
+> pi's built-in tools into the same sandbox, for which the agent's own VM drops
+> out of the picture and workspace paths are used as-is (the workspace is
+> direct-mounted at its host absolute path inside the sandbox, so no
+> `/workspace` hop is involved). See
+> [sandbox/README.md](sandbox/README.md) and
+> [security.md](security.md#execution-backend-built-in-tools-routed-into-the-sandbox).
+
 ## Topology
 
 ```
@@ -65,7 +75,7 @@ host macOS  (trusted operator)
 | Host env confidentiality | `DOCKER_*`/`COMPOSE_*` always stripped; secure by default (only a minimal safe set is forwarded); `DOCKER_SANDBOX_ENV_ALLOWLIST` opts in to specific vars, `_PASSTHROUGH` opts out entirely; `docker_verify` audits the active mode |
 | Host files untouched | Only the session workspace is mounted into the sandbox; host `~/.docker`, `~/.ssh` etc. are not visible (audited by `docker_verify`) |
 | Project writes (optional) | `DOCKER_SANDBOX_WORKSPACE_RO=1` → project mounted read-only; all project writes must go through the agent's own tools |
-| Ports | Published on host `127.0.0.1` only (`sbx ports`); the agent probes them with `docker_curl` (host-side fetch); the agent's VM cannot reach host loopback |
+| Ports | Published on host `127.0.0.1` only (`sbx ports`); the agent probes them with `docker_curl` (host-side fetch, confined to ports this sandbox published); the agent's VM cannot reach host loopback |
 
 ## Ports & networking (verified rules)
 
@@ -98,7 +108,8 @@ host macOS  (trusted operator)
    pokes the sandbox every ~60s while the pi session is alive).
 6. **Verification paths**:
    - Agent → `docker_curl http://127.0.0.1:<hostport>/` (host-side fetch;
-     GET/POST/PUT with optional body).
+     GET/POST/PUT with optional body; only ports this sandbox published are
+     reachable).
    - Sandbox-internal → `docker_exec` against `127.0.0.1:<port>` (same docker
      network).
    - Human → open `http://localhost:<hostport>/` on the host.