@stixxert/pi-docker-sandbox 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,271 @@
+# docker-sandbox-extension
+
+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`).
+
+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
+exposed to it**.
+
+## Why
+
+Agents that can deploy are powerful; agents that can reach your real docker
+daemon are a liability. With this extension:
+
+- Every docker operation happens inside a disposable microVM with its own
+  daemon — nothing appears in the host's `docker ps`.
+- The extension **never touches a host docker socket or CLI**; it only shells
+  out to `sbx exec`. There is no fallback path to the host daemon.
+- Docker env vars (`DOCKER_HOST`, `DOCKER_CONTEXT`, …) are scrubbed and the
+  inner CLI is pinned to the sandbox daemon, so leaked host config cannot
+  redirect it.
+- `docker_verify` runs a live isolation audit (PASS/FAIL per check).
+
+## Requirements
+
+- [pi](https://pi.dev) (the extension runs in the host pi process)
+- The Docker Sandboxes CLI (`sbx`) — a standalone binary; **no Docker Desktop
+  required**
+- A host hypervisor for `sbx` to boot microVMs on. The sandbox is a real VM
+  with its own kernel, so the virtualization backend is platform-specific:
+  - **macOS 14 (Sonoma)+ on Apple silicon** — uses Apple's Virtualization
+    framework (Intel Macs are not supported by `sbx`)
+  - **Linux x86_64 with KVM** — needs hardware virtualization and your user
+    in the `kvm` group (`lsmod | grep kvm` should list `kvm_intel` /
+    `kvm_amd` / `kvm_arm64`)
+
+See [Install](#install) for one-line installs per platform.
+
+## Install
+
+**1. Install the `sbx` CLI** (one line per platform):
+
+macOS — Apple silicon, Sonoma 14+:
+
+```bash
+brew install docker/tap/sbx && sbx login
+```
+
+Linux — Debian/Ubuntu x86_64 with KVM:
+
+```bash
+curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh && sudo apt-get install -y docker-sbx && sudo usermod -aG kvm "$USER" && newgrp kvm && sbx login
+```
+
+First `sbx login` opens a browser for Docker OAuth and asks you to pick a
+default network policy ("Balanced" is a good default). `newgrp kvm` drops you
+into a shell with the group active; log out and back in for it to stick.
+
+**2. Install the extension** — as a pi package (recommended). The repo
+declares itself via the `pi` manifest in `package.json` (loads `index.ts`),
+so it installs like any pi package — from git, npm, or a local checkout:
+
+```bash
+pi install git:git@github.com:stixxert/pi-docker-sandbox
+# or from npm:
+pi install npm:@stixxert/pi-docker-sandbox
+# or try it for a single run without installing:
+pi -e git:git@github.com:stixxert/pi-docker-sandbox
+# or install the checkout you're developing in:
+pi install ./path/to/this/repo
+```
+
+**Manually** — the extension is a single file with no build step, so you can
+copy it to one of pi's auto-discovery locations, then `/reload` in pi:
+
+```bash
+cp index.ts ~/.pi/agent/extensions/docker-sandbox.ts   # global, or
+cp index.ts .pi/extensions/docker-sandbox.ts           # project-local
+```
+
+or load it directly for a quick test:
+
+```bash
+pi -e ./index.ts
+```
+
+The sandbox is **auto-provisioned on first use** (2 CPU / 2 GB, session
+workspace mounted). No manual steps required.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `docker_status` | Sandbox presence, engine version, resources |
+| `docker_verify` | Live isolation audit (PASS/FAIL per check) |
+| `docker_resources` | VM memory/cpu/disk + docker disk + per-container usage, with warnings |
+| `docker_prune` | Reclaim sandbox space (`docker system prune -af`) |
+| `docker_ps` / `docker_images` | List containers / images in the sandbox |
+| `docker_pull` | Pull an image into the sandbox daemon |
+| `docker_run` | Run a container (ports, env, memory cap, volumes, network, restart; detach or foreground) |
+| `docker_logs` / `docker_exec` | Inspect a running container |
+| `docker_build` | Build an image from a workspace directory |
+| `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_sandbox_rm` | Remove this session's sandbox (microVM + everything inside) |
+| `docker_gc` | Sweep stale `pi-sbx-*` sandboxes left by crashed sessions |
+
+All containers get the label `com.pi.sandbox=true`.
+
+## Multi-session sandbox naming
+
+Each pi session gets its own sandbox named `pi-sbx-<pid>-<random>` — unique per
+process, never repeats, and independent of any host environment (herdr, tmux,
+terminal). Concurrent sessions never share docker state. For a stable,
+persistent name (e.g. a shared sandbox reused across restarts), pin
+`DOCKER_SANDBOX` explicitly.
+
+- `DOCKER_SANDBOX` — pin an explicit (e.g. shared, persistent) sandbox name.
+- `DOCKER_SANDBOX_AUTOCREATE=0` — disable auto-provisioning (create manually
+  with `sbx create --name <name> shell <workspace-dir>` from a host pane).
+- `DOCKER_SANDBOX_CPUS` / `DOCKER_SANDBOX_MEMORY` — resources for
+  auto-created sandboxes (default `2` / `2g`; sbx minimum memory is 1 GiB,
+  values below are clamped).
+- `DOCKER_SANDBOX_WORKSPACE_RO=1` — mount the project **read-only** into the
+  sandbox (sbx requires the primary workspace to be rw, so a small scratch
+  primary is created and the project is mounted as a read-only additional
+  workspace). The agent writes project files through its normal tools
+  (`/workspace` in its own VM); the sandbox and any container it runs can
+  only read the project — even bind mounts from it are read-only. Builds and
+  compose still work; volume binds sourced from the project get `:ro` added
+  automatically.
+- `DOCKER_SANDBOX_KEEPALIVE=1` — keep the sandbox VM running while the pi
+  session is alive (watchdog pokes it every ~60s), defeating sandboxd's
+  idle-stop for leave-it-running deploy flows.
+- `DOCKER_SANDBOX_TEMPLATE=<name>` — use a pre-baked `sbx template` for
+  auto-created sandboxes (avoids re-pulling common images every session;
+  create with `sbx template save <name>` from a prepared sandbox).
+
+## Ports (verified rules)
+
+- sbx does **not** auto-forward docker `-p` mappings — the extension
+  explicitly publishes them (`sbx ports <sandbox> --publish H:C`) after
+  `docker_run`/`docker_compose up` and reports the host URL
+  (`http://127.0.0.1:<hostport>/`). `docker_rm` unpublishes again.
+- **Host ports < 1024** are privileged in macOS/Unix for any non-root process
+  (standard OS rule, not an sbx limitation) — irrelevant for dev (dev servers
+  run on 3000/8080/…) and only matters when reproducing a production URL
+  without a port number.
+- **Avoid container port 80** — the sandbox's port proxy resets it (verified:
+  node, busybox, nginx). Use 3000/8080/8000 (`docker_init` templates do);
+  nginx-style images just need their listen port changed — the host URL is
+  unaffected.
+- **UDP**: `sbx ports` accepts `H:C/udp` and a round-trip was verified
+  (node dgram echo); use `ports=["5000:5000/udp"]`.
+- **Idle-stop**: sandboxd stops sandbox VMs ~2–4 min after the last `sbx`
+  call; `docker_run` defaults detached services to `restart=unless-stopped`
+  and `sbx ports` mappings survive VM restarts. For leave-it-running flows
+  set `DOCKER_SANDBOX_KEEPALIVE=1`.
+- **Reboot cleanup**: `docker_rm`/`docker_compose down` unpublish port
+  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>/`.
+
+See [boundary.md](boundary.md) for the full agent ↔ sbx boundary
+model and usage guide (agent + human). The extension is not dependent on
+gondolin — it runs in the host pi process and relies only on the
+`/workspace` ↔ host-cwd path convention.
+
+## Sandbox lifecycle
+
+| Event | What happens |
+|-------|--------------|
+| First `docker_*` call | Sandbox is auto-provisioned (unique name, session workspace mounted) and a **detached watchdog** is armed on the pi process |
+| Session idle | Nothing — the sandbox stays ready; `sbx exec` auto-starts the VM if it was stopped |
+| Session ends (exit, Ctrl+C/D, SIGHUP/SIGTERM, `/new`, `/resume`, `/fork`) | `session_shutdown` hook runs teardown immediately (fast path) |
+| Session dies hard (`kill -9`, process-manager kill) | The watchdog (which polls the pi process and survives it) performs the same teardown within seconds — no event required |
+| Watchdog also missed (host reboot) | Sandbox left stopped; the GC sweep reclaims it at the next session start |
+| Manual | `docker_sandbox_rm` (this session's sandbox) / `docker_gc` (stale sandboxes) |
+
+Teardown policy (`DOCKER_SANDBOX_TEARDOWN`, default `remove` for session
+sandboxes, `none` for pinned `DOCKER_SANDBOX` names):
+
+- `remove` — delete the microVM and everything inside it (images, containers,
+  volumes). State is rebuildable; nothing accumulates.
+- `stop` — keep state, free memory; the VM restarts on next use.
+- `none` — leave running (use for shared/persistent sandboxes).
+
+Crash safety net: at every session start (and via `docker_gc [hours]`) the
+extension sweeps sandboxes named `pi-sbx-*` that are **stopped**, not the
+current session's, and older than `DOCKER_SANDBOX_GC_HOURS` (default `24`).
+Note: `DOCKER_SANDBOX_GC_HOURS=0` **disables the automatic session-start
+sweep**; the `docker_gc` tool still accepts `hours=0` for a manual any-age
+sweep. Running sandboxes and non-pi sandboxes are never touched.
+
+## Path mapping
+
+The agent's VM mounts the workspace at `/workspace`; the extension maps
+`/workspace/<rel>` → `<host pi cwd>/<rel>`, which is also the path inside the
+sandbox (the workspace is direct-mounted there). So `docker_build` contexts
+and `docker_run` volume binds "just work".
+
+## Example deploy flow
+
+```
+docker_status
+docker_init(context=/workspace/myapp)            # scaffold Dockerfile
+docker_build(context=/workspace/myapp, tag=myapp:latest)
+docker_run(image=myapp:latest, name=web, ports=["8080:80"], detach=true)
+docker_logs(id=web, tail=50)
+docker_verify                                    # confirm isolation
+docker_compose(file=/workspace/myapp/compose.yaml, action=up)
+```
+
+## Dockerfiles
+
+Dockerfiles are ordinary files in the workspace — the agent authors/edits
+them with its normal tools and builds them with `docker_build`. `docker_init`
+bootstraps a sensible one for node (npm or pnpm), go, python, rust, or a
+generic alpine base, plus a `.dockerignore` and optional `compose.yaml`.
+
+## Security
+
+See [security.md](security.md) for the threat model, design
+guarantees, and the `docker_verify` check list. For maximum project
+protection, set `DOCKER_SANDBOX_WORKSPACE_RO=1`: the sandbox then has the
+project mounted read-only and **all** project writes flow through the agent's
+own sandboxed tools instead.
+
+## Host env forwarding (secure by default)
+
+The extension passes **only a minimal safe set** of the pi host's environment
+into the sandbox — `HOME`, `PATH`, `USER`, `LOGNAME`, `TMPDIR`, `SHELL`,
+`LANG`, `TERM` (non-secret vars the `sbx` CLI and shells need). `DOCKER_*` /
+`COMPOSE_*` are **always** stripped — a leaked `DOCKER_HOST` could redirect
+the inner docker client. Everything else is confined by default:
+
+- `DOCKER_SANDBOX_ENV_ALLOWLIST="A,B"` — opt in precisely: forward the
+  minimal set plus exactly `A` and `B` (e.g. the vars your compose file
+  interpolates with `${VAR}`). Docker-affecting vars cannot be allowlisted.
+- `DOCKER_SANDBOX_ENV_PASSTHROUGH=1` — explicit opt-out: forward the host env
+  minus the docker vars (raw `sbx exec` semantics, for legacy workflows that
+  rely on broad compose interpolation).
+
+Anything that runs inside the sandbox (containers, `docker_exec`'d commands)
+can read whatever reaches it — so host API keys and tokens stay confined
+unless you allowlist them deliberately. Prefer project-local `.env` files
+(gitignored) over host-env interpolation for compose secrets.
+`docker_verify` audits the active mode (`docker_status` reports it).
+
+## Development
+
+```sh
+npm install
+npm run typecheck   # strict tsc against the pi SDK types
+npm test            # loads the extension with a mock pi API; no sbx needed
+```
+
+The extension is a single file with no build step — `index.ts` is loaded
+directly by pi (copy it to `~/.pi/agent/extensions/docker-sandbox.ts`, or
+`pi install` the repo, see [Install](#install)). `package.json` doubles as the
+pi package manifest (`pi.extensions`) and declares typecheck-only dev deps;
+`tsconfig.json` keeps `tsc --strict` honest against the pi SDK types.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

package/boundary.md

@@ -0,0 +1,185 @@
+# The agent ↔ sbx boundary (and what the sandbox is for)
+
+This document defines what the Docker Sandbox is, what it is not, the exact
+trust boundary between the agent's own VM and the sandbox, and how to use it —
+for the **agent** and for the **human operator**.
+
+> **Not gondolin-specific.** This extension does **not depend on gondolin**
+> (pi's default agent micro-VM). It runs entirely in the host pi process and
+> relies on exactly one convention: the agent's workspace is mounted at
+> `/workspace`, which the extension maps to the host pi cwd
+> (`/workspace/<rel>` ↔ `<host cwd>/<rel>`). That mapping is a plain
+> host-side path substitution — no gondolin mechanism is involved, and the
+> same applies to any pi setup that mounts the workspace at `/workspace`.
+> Gondolin is used throughout this document simply as the concrete reference
+> deployment.
+
+## Topology
+
+```
+host macOS  (trusted operator)
+│
+├─ pi process (host) ── extension docker-sandbox.ts ── only channel to sbx
+│     │  path mapping: /workspace/<rel> ↔ <host cwd>/<rel>
+│     ▼
+│  agent's VM (e.g. gondolin)  │        sbx microVM (Docker Sandbox)
+│  └ /workspace (rw)           │        └ /Users/…/project (rw or :ro)
+│     agent's tools:           │           └ private docker daemon (own images,
+│     read/write/edit/bash     │              containers, volumes)
+│     (sandboxed by policy)    │
+└──────────────────────────────┴─────────────────────────────────────────────
+   same host directory mounted in both VMs (one mount, two views)
+```
+
+## What the sandbox is FOR
+
+- A **disposable, isolated execution environment for containerized
+  workloads**: build images, run services, `docker compose up`, test deploys —
+  without touching the host's docker or the agent's own VM.
+- A private docker daemon per pi session, with its own images/containers/
+  volumes, port-forwarded to host `localhost` only, torn down with the
+  session.
+- Deploy verification (health checks, logs, exec) inside a real container
+  runtime.
+
+## What the sandbox is NOT
+
+- ❌ Not a gateway to the host's docker (Docker Desktop / colima / dockerd).
+  The extension never opens a host docker socket and never invokes a host
+  `docker` CLI; there is no fallback path.
+- ❌ Not the place where the agent edits project files. Project files are
+  written with the agent's normal tools in its own VM (`/workspace`); the
+  sandbox reads them (build contexts, volume binds). With
+  `DOCKER_SANDBOX_WORKSPACE_RO=1` the sandbox physically cannot modify the
+  project.
+- ❌ Not a sandbox for the agent's file/network access — that is the agent's
+  own VM's job. The sbx sandbox only adds an isolated *docker runtime*.
+
+## Boundary guarantees (verified)
+
+| Property | How it's enforced |
+|---|---|
+| Agent's docker reach = its own sandbox only | Every tool derives the sandbox name from the session (`pi-sbx-<pid>-<random>`, or an explicit `DOCKER_SANDBOX`); no tool accepts a foreign sandbox name; `sbx` CLI and host docker socket are absent from the agent's VM |
+| One sandbox per session | Deterministic per-session name + auto-provision once; `docker_sandbox_rm` removes only that one; GC touches only stale `pi-sbx-*` sandboxes (never running ones, never non-pi ones) |
+| No host docker access | Transport is `sbx exec` only; `DOCKER_*`/`COMPOSE_*` env scrubbed; inner docker pinned via `-H unix:///var/run/docker.sock` |
+| 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 & networking (verified rules)
+
+1. **Publishing is explicit**: sbx does not auto-forward docker `-p`
+   mappings. The extension calls `sbx ports <sandbox> --publish H:C` after
+   `docker_run`/`docker_compose up` and reports the host URL
+   (`http://127.0.0.1:<hostport>/`). Compose port discovery reads both the
+   legacy `Ports` string and the structured `Publishers` array from
+   `docker compose ps --format '{{json .}}'`. `docker_rm` and
+   `docker_compose down` unpublish the container's mappings again (sbx would
+   otherwise leave stale mappings that answer with connection resets).
+2. **Host port ≥ 1024**: ports < 1024 are privileged in macOS/Unix for ANY
+   non-root process (`PermissionError: Errno 13`), not an sbx limitation.
+   Irrelevant for dev (dev servers use 3000/8080/…); only matters when
+   reproducing production URLs without a port number. Workaround if ever
+   needed: `sudo pfctl` port redirect or a reverse proxy on a high port.
+3. **Avoid container port 80**: the sandbox's port proxy resets connections
+   to container port 80 (verified with node, busybox httpd, nginx). Use
+   container ports like 3000/8080/8000 (the `docker_init` templates do); for
+   images that listen on 80 by default (e.g. nginx), reconfigure them — for
+   dev this is a one-line config change and the host URL is unaffected (the
+   host port is what appears in the URL).
+4. **UDP**: works. `sbx ports` accepts `H:C/udp`, and a host→sandbox UDP
+   round-trip was verified (node dgram echo server). Use `ports=["5000:5000/udp"]`.
+5. **Idle-stop**: sandboxd stops sandbox VMs ~2–4 minutes after the last
+   `sbx exec` client disconnects (not configurable via `sbx` CLI). Services
+   with `restart=unless-stopped` (the extension's default for detached runs)
+   come back on the next exec; `sbx ports` mappings survive. For
+   leave-it-running flows set `DOCKER_SANDBOX_KEEPALIVE=1` (the watchdog
+   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).
+   - Sandbox-internal → `docker_exec` against `127.0.0.1:<port>` (same docker
+     network).
+   - Human → open `http://localhost:<hostport>/` on the host.
+
+## How the AGENT should use it
+
+- Run `docker_status` first; then deploy with
+  `docker_init` → `docker_build` → `docker_run`/`docker_compose`.
+- Verify what you started: `docker_curl` (host), `docker_logs`, `docker_exec`.
+- Do not attempt to reach the host's docker (there is no path), and do not
+  invent sandbox names — the session sandbox is `sessionSandboxName()` and
+  every tool targets it.
+- Use non-80 container ports and ≥1024 host ports.
+- Clean up: `docker_rm`/`docker_compose down` for containers;
+  `docker_sandbox_rm` for the whole sandbox; `docker_gc` for stale ones.
+
+## How the HUMAN should use it
+
+- Prereqs: `sbx` CLI (`brew install docker/tap/sbx`), `sbx login`, `sandboxd`
+  running (`sbx daemon status`). Docker Desktop is NOT needed.
+- The sandbox is auto-provisioned on first use; manage it with
+  `sbx ls` / `sbx stop <name>` / `sbx rm --force <name>`.
+- Tune via env: `DOCKER_SANDBOX` (pin a name), `DOCKER_SANDBOX_TEARDOWN`
+  (`remove`/`stop`/`none`), `DOCKER_SANDBOX_WORKSPACE_RO=1`,
+  `DOCKER_SANDBOX_GC_HOURS`, `DOCKER_SANDBOX_CPUS`/`_MEMORY`, and env
+  confinement: `DOCKER_SANDBOX_ENV_ALLOWLIST="A,B"` (opt in) /
+  `DOCKER_SANDBOX_ENV_PASSTHROUGH=1` (opt out of the secure default).
+- A sandbox is a dev/test environment, not a security boundary against the
+  host user; the workspace mount is the only host surface it sees.
+
+## Resources & failure modes (how the agent finds out, what to do)
+
+The sandbox has fixed limits set at creation (`DOCKER_SANDBOX_CPUS`, default 2;
+`DOCKER_SANDBOX_MEMORY`, default 2g). The agent is notified of pressure in two
+ways:
+
+1. **Indirect (always):** docker tool calls surface it — builds fail with
+   no-space errors, `docker_ps` shows `Exited (137)` / `Restarting (137)`
+   (OOM-kill), pulls time out. The extension now has a 120s default timeout on
+   sandbox calls so an OOM-hung VM fails the tool call instead of hanging the
+   turn.
+2. **Direct (new):** `docker_resources` reports VM memory/cpu/disk, docker disk
+   (images/containers/build cache), and per-running-container cpu/mem, and
+   warns above 85% memory or disk. Run it when deploys fail or containers exit
+   abnormally.
+
+Remediation ladder (in the agent's toolset):
+
+| Symptom | Action |
+|---|---|
+| High memory / OOM kills | `docker_rm`/`docker_stop` heavy containers; cap them with `docker_run(memory=…)`; raise `DOCKER_SANDBOX_MEMORY` and recreate (`docker_sandbox_rm` → next call re-provisions) |
+| High disk / no-space builds | `docker_prune` (optionally `volumes=true`) |
+| Container restart-looping on OOM | `docker_stop` it; use `restart=no` for memory-capped containers (restart policy + cap = infinite restart loop) |
+| VM unresponsive (sandboxd OOM) | `sbx ls`/`sbx stop <name>` from a host pane, or `docker_sandbox_rm` + recreate with bigger limits |
+
+Caveat: resources are fixed at sandbox creation — changing `DOCKER_SANDBOX_CPUS`/
+`_MEMORY` requires recreating the sandbox (session-scoped sandboxes are
+recreated automatically on the next `docker_*` call after removal).
+
+## Known limitations / areas to look into
+
+- **Container port 80** and **host ports < 1024** do not forward (see above);
+  both are dev-irrelevant with the documented workarounds.
+- **Idle-stop**: sandboxd stops idle sandbox VMs ~2–4 min after the last sbx
+  call (not configurable); services auto-recover via `restart=unless-stopped`,
+  or keep the VM up with `DOCKER_SANDBOX_KEEPALIVE=1`.
+- **Host reboot** kills both teardown mechanisms; cleanup happens via the GC
+  at the next session start, or manually with `sbx rm --force $(sbx ls -q | grep pi-sbx)`.
+- **GC is sibling-safe**: every session writes an owner marker
+  (`<name>.pi-owner` with its pid) next to the sandbox state; the GC only
+  removes stopped `pi-sbx-*` sandboxes whose owner process is dead. Concurrent
+  sessions never reap each other's sandboxes, even with
+  `DOCKER_SANDBOX_GC_HOURS=0` (verified). Edge case: if the OS reuses a dead
+  session's pid, that stale sandbox lingers until manual cleanup — rare (needs
+  a crashed session whose teardown also failed) and harmless.
+- **Concurrent sessions** each get their own sandbox; published host ports
+  must be unique across sessions (a taken host port falls back to an
+  ephemeral port).
+- **Image pulls repeat per session** (each sandbox is a fresh VM). Pre-bake a
+  template to fix: `sbx template save <name>` from a sandbox with the images
+  pre-pulled, then set `DOCKER_SANDBOX_TEMPLATE=<name>` (or pass `--template`
+  to `sbx create`). Check `sbx template save --help` for exact syntax.
+- sbx itself (VM kernel, port proxy, idle-stop) is Docker's product; its
+  quirks above are tracked here so behavior changes are noticed.