@stixxert/pi-docker-sandbox 0.1.0 → 1.1.0

package/sandbox/transport.ts

@@ -0,0 +1,377 @@
+/**
+ * Exec transport for the sbx execution backend.
+ *
+ * A transport is "run a command in an isolated Linux environment and stream
+ * its output". Two backends implement it:
+ *
+ *   - `sbx`    — Docker Sandboxes (`sbx exec <sandbox> -- ...`). The product
+ *                path: what makes pi run *against a sandbox* instead of
+ *                inside one.
+ *   - `docker` — a plain container (`docker exec <container> -- ...`). Useful
+ *                on Linux hosts, and it is what lets the ops layer be tested
+ *                end-to-end in environments where `sbx` cannot run at all
+ *                (sbx needs a host hypervisor; it cannot nest).
+ *
+ * Both backends have the identical `exec <target> -- argv...` shape, so a
+ * single implementation is parameterised by (binary, target).
+ *
+ * Nothing here ever touches a host docker daemon through a socket: the `sbx`
+ * backend shells out to the `sbx` CLI only, and the `docker` backend is
+ * opt-in and explicit.
+ */
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ensureSandbox, findSbxCli, runSbxCli, scrubbedEnv } from "../index.ts";
+
+/* ------------------------------------------------------------------ */
+/* project-scoped sandbox naming                                       */
+/* ------------------------------------------------------------------ */
+
+/** Same shape the kernel accepts for DOCKER_SANDBOX names. */
+function sanitizeName(value: string): string {
+	return value
+		.replace(/[^A-Za-z0-9._+-]/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 60);
+}
+
+/** Nearest ancestor containing a VCS root — the same "what is this project?" rule sbxpi uses. */
+function findProjectRoot(startDir: string): string {
+	let dir = startDir;
+	for (;;) {
+		for (const marker of [".git", ".hg", ".svn"]) {
+			if (fs.existsSync(path.join(dir, marker))) return dir;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) return startDir;
+		dir = parent;
+	}
+}
+
+/**
+ * Default the sandbox to ONE PER PROJECT rather than one per process.
+ *
+ * This is the difference between a ~15 s startup and a ~1 s one. The kernel
+ * derives `pi-sbx-<pid>-<rand>` and REMOVES it at teardown, so every pi run had
+ * to `sbx create` a brand-new VM — including re-preparing its image layers —
+ * while a pinned name makes teardown `none`, so the next run reuses the
+ * existing sandbox (sandboxd still idle-stops the VM when pi exits, but the VM,
+ * its pulled images and anything installed in it survive).
+ *
+ * It also matches sbxpi, which keeps one sandbox per project, and it makes runs
+ * from a subdirectory land in the same sandbox because the name is derived from
+ * the project root, not the cwd.
+ *
+ * An explicit DOCKER_SANDBOX always wins; SBX_EPHEMERAL=1 restores the old
+ * per-session behaviour.
+ */
+export function defaultProjectSandbox(startDir: string): string | undefined {
+	const explicit = (process.env.DOCKER_SANDBOX ?? "").trim();
+	if (explicit) return sanitizeName(explicit);
+	if (/^(1|true|yes|on)$/i.test((process.env.SBX_EPHEMERAL ?? "").trim())) return undefined;
+
+	const root = findProjectRoot(startDir);
+	const name = `pi-sbx-${sanitizeName(path.basename(root) || "project")}-${createHash("sha256").update(root).digest("hex").slice(0, 8)}`;
+	process.env.DOCKER_SANDBOX = name;
+	return name;
+}
+
+/* ------------------------------------------------------------------ */
+/* optional timing (SBX_PI_DEBUG=1, matching the launcher's convention) */
+/* ------------------------------------------------------------------ */
+
+function debugEnabled(): boolean {
+	return /^(1|true|yes|on)$/i.test((process.env.SBX_PI_DEBUG ?? process.env.SBX_DEBUG ?? "").trim());
+}
+
+function note(message: string): void {
+	if (debugEnabled()) console.error(`[sbx] ${message}`);
+}
+
+/** Time an async startup phase; a no-op passthrough unless debugging is on. */
+async function timed<T>(label: string, fn: () => Promise<T>): Promise<T> {
+	if (!debugEnabled()) return fn();
+	const started = Date.now();
+	try {
+		return await fn();
+	} finally {
+		console.error(`[sbx] ${label}: ${Date.now() - started}ms`);
+	}
+}
+
+export interface ExecOptions {
+	/** Streamed stdout+stderr (interleaved in arrival order, like a terminal). */
+	onData?: (chunk: Buffer) => void;
+	/** Abort the command (SIGKILL the child). */
+	signal?: AbortSignal;
+	/** Timeout in SECONDS (matches pi's BashOperations contract). */
+	timeout?: number;
+}
+
+export interface ExecOutcome {
+	/** null when the process was killed by a signal. */
+	exitCode: number | null;
+	stdout: Buffer;
+	stderr: Buffer;
+}
+
+export interface ExecTransport {
+	readonly kind: "sbx" | "docker";
+	readonly target: string;
+	/** Run `argv[0] argv[1] ...` inside the sandbox. No shell is implied. */
+	exec(argv: string[], opts?: ExecOptions): Promise<ExecOutcome>;
+}
+
+/** Run argv inside the sandbox; buffers stdout/stderr, optionally streams them. */
+function spawnExec(bin: string, prefix: string[], argv: string[], opts: ExecOptions = {}): Promise<ExecOutcome> {
+	return new Promise((resolve, reject) => {
+		if (opts.signal?.aborted) {
+			reject(new Error("aborted"));
+			return;
+		}
+
+		const child = spawn(bin, [...prefix, ...argv], {
+			// Minimal safe env: HOME/PATH/USER/... minus DOCKER_*/COMPOSE_*.
+			env: scrubbedEnv(),
+			stdio: ["ignore", "pipe", "pipe"],
+			// Own process group, so an abort/timeout can kill the CLI *and* any
+			// children it spawned here, instead of orphaning them.
+			detached: true,
+		});
+
+		const stdout: Buffer[] = [];
+		const stderr: Buffer[] = [];
+
+		// Stream interleaved, and keep the raw streams for callers that buffer.
+		child.stdout?.on("data", (chunk: Buffer) => {
+			stdout.push(chunk);
+			opts.onData?.(chunk);
+		});
+		child.stderr?.on("data", (chunk: Buffer) => {
+			stderr.push(chunk);
+			opts.onData?.(chunk);
+		});
+
+		child.on("error", (err) => {
+			cleanup();
+			reject(err);
+		});
+
+		let timedOut = false;
+		// SIGKILL the whole process group: the direct child is the sbx/docker CLI,
+		// whose own children would otherwise survive. (A process already running
+		// INSIDE the sandbox VM is not reachable this way and may outlive the
+		// call - see sandbox/README.md.)
+		const killTree = () => {
+			try {
+				if (child.pid) process.kill(-child.pid, "SIGKILL");
+				else child.kill("SIGKILL");
+			} catch {
+				child.kill("SIGKILL");
+			}
+		};
+		const timer =
+			opts.timeout && opts.timeout > 0
+				? setTimeout(() => {
+						timedOut = true;
+						killTree();
+					}, opts.timeout * 1000)
+				: undefined;
+
+		const onAbort = () => killTree();
+		opts.signal?.addEventListener("abort", onAbort, { once: true });
+
+		function cleanup() {
+			if (timer) clearTimeout(timer);
+			opts.signal?.removeEventListener("abort", onAbort);
+		}
+
+		child.on("close", (code, signal) => {
+			cleanup();
+			if (opts.signal?.aborted) {
+				reject(new Error("aborted"));
+				return;
+			}
+			if (timedOut) {
+				reject(new Error(`timeout:${opts.timeout}`));
+				return;
+			}
+			resolve({
+				exitCode: signal ? null : code,
+				stdout: Buffer.concat(stdout),
+				stderr: Buffer.concat(stderr),
+			});
+		});
+	});
+}
+
+/** `sbx exec <sandbox> -- ...` — the product path. */
+export function createSbxTransport(sandboxName: string): ExecTransport {
+	const bin = findSbxCli();
+	return {
+		kind: "sbx",
+		target: sandboxName,
+		exec: (argv, opts) => spawnExec(bin, ["exec", sandboxName, "--"], argv, opts),
+	};
+}
+
+/**
+ * `docker exec <container> -- ...` — alternate/test backend.
+ *
+ * Deliberately NOT the default and never implicit: the default path is sbx,
+ * and a container is only used when a container id is supplied explicitly.
+ */
+export function createDockerTransport(container: string): ExecTransport {
+	return {
+		kind: "docker",
+		target: container,
+		// docker takes `exec <container> <cmd...>` — it has no `--` separator
+		// (unlike sbx), so the prefix differs from the sbx backend.
+		exec: (argv, opts) => spawnExec("docker", ["exec", container], argv, opts),
+	};
+}
+
+/**
+ * Where template/build.sh records the ref of the lightweight template it built.
+ * The handshake is a file rather than configuration so that the user never has
+ * to set anything: build the template (or let a launcher build it) and the next
+ * session picks it up.
+ */
+function templateRefFile(): string {
+	const cache = (process.env.XDG_CACHE_HOME ?? "").trim() || path.join(os.homedir(), ".cache");
+	return path.join(cache, "pi-sbx-lite", "template-ref");
+}
+
+/**
+ * Does `sbx template ls` list `tag`? Handles both known output layouts (a
+ * `<repo> <version>` table and a flat `<repo>:<version>` list) by matching on
+ * the repository basename and version rather than on column positions.
+ */
+export function templateListHas(output: string, tag: string): boolean {
+	const separator = tag.lastIndexOf(":");
+	if (separator < 0) return false;
+	const wantedRepo = tag.slice(0, separator).split("/").pop();
+	const wantedVersion = tag.slice(separator + 1);
+	for (const raw of output.split("\n")) {
+		const line = raw.trim();
+		if (!line || /^REPOSITORY/i.test(line)) continue;
+		const parts = line.split(/\s+/);
+		const first = parts[0] ?? "";
+		const basename = first.split("/").pop();
+		// Flat layout: one token, "<repo path>/<name>:<version>" — so the tag is
+		// the LAST path segment, not the whole token.
+		if (parts.length === 1 && basename === tag) return true;
+		// Table layout: "<repo> <version>" in separate columns.
+		if (basename === wantedRepo && parts[1] === wantedVersion) return true;
+	}
+	return false;
+}
+
+/**
+ * Adopt the lightweight template if one has been recorded AND it still exists.
+ *
+ * Never fatal and never required: if the file is absent, unreadable, or names a
+ * template that has since been removed, we simply leave DOCKER_SANDBOX_TEMPLATE
+ * unset and the sandbox is created from the stock base. That is what makes the
+ * "the user does nothing" guarantee safe — a missing template degrades speed,
+ * it never turns into a failure.
+ *
+ * An explicit DOCKER_SANDBOX_TEMPLATE always wins.
+ */
+async function useRecordedTemplate(): Promise<void> {
+	if ((process.env.DOCKER_SANDBOX_TEMPLATE ?? "").trim()) return;
+	let ref: string;
+	try {
+		ref = fs.readFileSync(templateRefFile(), "utf8").trim();
+	} catch {
+		return; // never built — stock base is fine
+	}
+	if (!ref) return;
+	try {
+		const tag = ref.split("/").slice(-1)[0]; // docker.io/library/x:y -> x:y
+		const listed = await runSbxCli(["template", "ls"], 30_000);
+		if (templateListHas(`${listed.stdout}\n${listed.stderr}`, tag)) {
+			process.env.DOCKER_SANDBOX_TEMPLATE = ref;
+		}
+	} catch {
+		/* verification failed: fall back to the stock base rather than gamble */
+	}
+}
+
+/**
+ * Resolve the transport for this session.
+ *
+ * `SBX_BACKEND=docker` + `SBX_DOCKER_CONTAINER=<id>` opts into the container
+ * backend (test/alternate); anything else auto-provisions and targets an sbx
+ * sandbox via the shared kernel.
+ */
+export async function resolveTransport(): Promise<ExecTransport> {
+	const startedAt = Date.now();
+	const backend = (process.env.SBX_BACKEND ?? "sbx").trim().toLowerCase();
+	if (backend === "docker") {
+		const container = (process.env.SBX_DOCKER_CONTAINER ?? "").trim();
+		if (!container) throw new Error("SBX_BACKEND=docker requires SBX_DOCKER_CONTAINER=<container id or name>");
+		note(`backend=docker container=${container} (${Date.now() - startedAt}ms)`);
+		return createDockerTransport(container);
+	}
+	// Both must run BEFORE ensureSandbox(): the first chooses the template it
+	// creates from, the second arms the watchdog that reads the keepalive flag.
+	await timed("template", () => useRecordedTemplate());
+	defaultKeepaliveOn();
+	const sandbox = await timed("ensure sandbox (create if missing)", () => ensureSandbox());
+	note(
+		`backend=sbx sandbox=${sandbox} template=${process.env.DOCKER_SANDBOX_TEMPLATE ?? "stock base"} ` +
+			`keepalive=${process.env.DOCKER_SANDBOX_KEEPALIVE} total=${Date.now() - startedAt}ms`,
+	);
+	return createSbxTransport(sandbox);
+}
+
+/**
+ * Keep the sandbox VM running for as long as the pi process lives.
+ *
+ * sandboxd stops an idle sandbox ~2-4 min after the last `sbx` call, so
+ * without this, the first tool call after any pause pays a multi-second VM
+ * boot — the only overhead in this backend that is actually noticeable. The
+ * backend therefore defaults keepalive ON, while an explicit
+ * `DOCKER_SANDBOX_KEEPALIVE=0` still wins.
+ *
+ * Note this keeps the VM *running*; it does not keep it *existing*. Teardown is
+ * still governed by DOCKER_SANDBOX_TEARDOWN (default `remove` for a
+ * session-scoped sandbox), so the sandbox dies with the pi process — pin
+ * DOCKER_SANDBOX and use `TEARDOWN=stop` if you want docker images to survive
+ * between runs.
+ */
+function defaultKeepaliveOn(): void {
+	if ((process.env.DOCKER_SANDBOX_KEEPALIVE ?? "").trim() === "") {
+		process.env.DOCKER_SANDBOX_KEEPALIVE = "1";
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/* argv-safe shell helpers                                             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Single-quote a value for /bin/sh. Safe for arbitrary bytes except NUL
+ * (which cannot appear in an argv anyway).
+ */
+export function shQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Build argv for `sh -c <script> <$0> <args...>`.
+ *
+ * Passing user values as POSITIONAL params ($1, $2, ...) instead of splicing
+ * them into the script means paths and content can never be reinterpreted as
+ * shell syntax or as options — the same reason the docker_* tools validate
+ * their args.
+ */
+export function shArgs(script: string, ...args: string[]): string[] {
+	return ["sh", "-c", script, "sbx-ops", ...args];
+}

package/sandbox/try.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+#
+# try.sh — try the sbx execution backend for ONE pi run.
+#
+# Loads the extension with `pi -e` (the same way `pix` loads gondolin), so
+# NOTHING is installed and no settings are touched. If it creates a container or
+# a sandbox for you, it cleans it up again on exit.
+#
+#   bash sandbox/try.sh                      # auto: sbx if usable, else docker
+#   bash sandbox/try.sh --docker             # force a local container
+#   bash sandbox/try.sh --sbx                # force a real Docker Sandbox
+#   bash sandbox/try.sh --discover           # also load your discovered extensions
+#                                            # (only if none of them is a router)
+#   bash sandbox/try.sh --image sbx-lite     # container image for the docker path
+#   bash sandbox/try.sh --keep               # leave the container running
+#   bash sandbox/try.sh -p "run uname -a"    # extra args are passed to pi
+#
+# Note: this extension and the gondolin extension both override the same
+# built-in tools, so exactly one of them can be loaded. try.sh therefore runs pi
+# with `--no-extensions` and re-adds only what is needed (this extension, plus
+# env-keys for credentials). Use --discover to opt out of that.
+#
+# The docker path exists so the backend can be exercised on a machine without
+# sbx (including inside another sandbox, where sbx cannot run). It is the same
+# ops layer, only the `exec <target> --` verb differs.
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+EXT="$HERE/index.ts"
+REPO="$(cd "$HERE/.." && pwd)"
+AGENT_DIR="${PI_AGENT_DIR:-$HOME/.pi/agent}"
+
+MODE="auto"
+IMAGE="${SBX_TRY_IMAGE:-debian:stable-slim}"
+CONTAINER="sbx-try-$$"
+KEEP=0
+DISCOVER=0
+PI_ARGS=()
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+	--docker) MODE="docker" ;;
+	--sbx) MODE="sbx" ;;
+	--keep) KEEP=1 ;;
+	--discover) DISCOVER=1 ;;
+	--image)
+		IMAGE="$2"
+		shift
+		;;
+	-h | --help)
+		sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'
+		exit 0
+		;;
+	--)
+		shift
+		PI_ARGS+=("$@")
+		break
+		;;
+	*)
+		# Anything else is a pi argument (e.g. -p "...", --model ...).
+		PI_ARGS+=("$1")
+		;;
+	esac
+	shift
+done
+
+cleanup() {
+	if [ "$MODE" = "docker" ] && [ "$KEEP" != "1" ]; then
+		docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
+	fi
+}
+trap cleanup EXIT
+
+# ── choose a backend ──────────────────────────────────────────────────────
+if [ "$MODE" = "auto" ]; then
+	if command -v sbx >/dev/null 2>&1 && sbx ls >/dev/null 2>&1; then
+		MODE="sbx"
+	else
+		MODE="docker"
+	fi
+fi
+
+if [ "$MODE" = "docker" ]; then
+	command -v docker >/dev/null 2>&1 || {
+		echo "try: no sbx and no docker on PATH — cannot try the backend here." >&2
+		echo "try: on your host, install sbx (brew install docker/tap/sbx && sbx login) or docker." >&2
+		exit 1
+	}
+
+	# Mount the project at its HOST absolute path: that identity is what the
+	# whole backend relies on, so the trial must reproduce it.
+	echo "try: starting container $CONTAINER from $IMAGE (project mounted at $PWD)"
+	docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
+	docker run -d --name "$CONTAINER" -v "$PWD:$PWD" -w "$PWD" "$IMAGE" sleep 86400 >/dev/null
+
+	export SBX_BACKEND=docker
+	export SBX_DOCKER_CONTAINER="$CONTAINER"
+	echo "try: routing pi's tools into the container (docker exec)"
+else
+	# Real sandbox: the extension auto-provisions it on first use.
+	if bash "$REPO/template/build.sh" --check >/dev/null 2>&1; then
+		echo "try: lightweight template already current"
+	else
+		echo "try: no lightweight template yet — sandboxes will use the stock base."
+		echo "try: build it once (optional, ~2 min):  bash $REPO/template/build.sh"
+	fi
+	echo "try: pi's tools will run in this project's sbx sandbox (auto-created)"
+fi
+
+echo "try: extension $EXT"
+
+# ── exactly one tool router may be loaded ────────────────────────────────
+# This extension and the gondolin extension both override the SAME built-ins
+# (read/write/edit/bash/ls/find/grep). pi rejects whichever registers second, so
+# with gondolin sitting in the global extensions dir the trial would either
+# error noisily or — worse, if load order ever flips — silently run with the
+# WRONG backend while appearing to work.
+#
+# So discovery is turned off and only what the trial needs is re-added
+# explicitly. `-e` paths still load under `-ne`, which is what it is for.
+EXT_ARGS=(-e "$EXT")
+
+if [ "$DISCOVER" = "1" ]; then
+	echo "try: --discover given: loading every discovered extension as well"
+elif [ -d "$AGENT_DIR/extensions/gondolin" ]; then
+	echo "try: gondolin is installed and would conflict — leaving it out of this run"
+fi
+
+# Credentials usually live in ~/.pi/env/keys.env, loaded by the env-keys
+# extension. Turning discovery off would silently drop the model API keys, so
+# it is re-added explicitly when present.
+if [ "$DISCOVER" != "1" ] && [ -d "$AGENT_DIR/extensions/env-keys" ]; then
+	EXT_ARGS+=(-e "$AGENT_DIR/extensions/env-keys")
+	echo "try: keeping env-keys (provider credentials)"
+fi
+
+echo
+
+# NOT `exec`: exec would replace this shell and the EXIT trap would never run,
+# leaking the container. Run pi as a child so cleanup always happens, and pass
+# its exit status through.
+#
+# `${ARR[@]+...}` rather than a bare "${ARR[@]}": under `set -u` an EMPTY array
+# expansion is an "unbound variable" error in bash 3.2, which is what macOS
+# ships as /bin/bash. The idiom expands to nothing when empty and to properly
+# quoted elements otherwise.
+set +e
+if [ "$DISCOVER" = "1" ]; then
+	pi ${EXT_ARGS[@]+"${EXT_ARGS[@]}"} ${PI_ARGS[@]+"${PI_ARGS[@]}"}
+else
+	pi -ne ${EXT_ARGS[@]+"${EXT_ARGS[@]}"} ${PI_ARGS[@]+"${PI_ARGS[@]}"}
+fi
+STATUS=$?
+set -e
+
+exit "$STATUS"

package/security.md

@@ -28,10 +28,16 @@ own sandbox microVM** and the host's docker is never exposed to it.
 4. **Per-session sandboxes.** Each pi session gets a uniquely named sandbox
    (`pi-sbx-<pid>-<random>`, or an explicit `DOCKER_SANDBOX`), auto-provisioned
    with only the session's workspace mounted. Two concurrent sessions cannot
-   share or observe each other's docker state.
+   share or observe each other's docker state. (The execution backend below
+   pins a per-project name instead, which makes the sandbox project-scoped and
+   no longer removed at exit — see that section.)
 5. **Filesystem.** Only the session workspace (the dir mounted at `/workspace`
    in the agent VM) is direct-mounted into the sandbox. Host `~/.docker`,
-   `~/.ssh`, `~/.agent`, and other host paths are not mounted.
+   `~/.ssh`, `~/.agent`, and other host paths are not mounted. Path mapping is
+   confined to the workspace: `/workspace/..` traversal, absolute host paths,
+   and symlinks that point outside the workspace are all rejected
+   (`mapHostPath`), so the agent cannot reach host paths outside the mounted
+   workspace via build contexts, volume binds, or `docker_init`.
 6. **Env confidentiality (secure by default).** `DOCKER_*`/`COMPOSE_*` are
    always stripped from every child env. By default only a minimal safe set
    (`HOME`, `PATH`, `USER`, `LOGNAME`, `TMPDIR`, `SHELL`, `LANG`, `TERM`) is
@@ -40,6 +46,12 @@ own sandbox microVM** and the host's docker is never exposed to it.
    `DOCKER_SANDBOX_ENV_PASSTHROUGH=1` (host env minus the docker vars).
    Anything running inside the sandbox can read whatever reaches it — this
    knob confines that surface.
+7. **Input validation.** Tool arguments that reach the docker CLI positionally
+   (container ids, image refs, tags, names) are validated to reject values that
+   start with `-` (which docker would parse as flags) or contain control
+   characters. `docker_run` validates port/volume/memory specs, and
+   `docker_curl` is restricted to a safe HTTP-method allowlist and a 1 MiB body
+   limit.
 
 ### Read-only workspace mode (`DOCKER_SANDBOX_WORKSPACE_RO=1`)
 
@@ -58,6 +70,43 @@ project as an **additional read-only** workspace. Consequences (all verified):
   its VM) — the intended trust boundary. The sandbox becomes a pure
   read-and-execute environment for the project.
 
+Read-only mode is **not** usable together with the execution backend below:
+that backend's `write`/`edit`/`mkdir` operate on the mounted project, so they
+would simply fail.
+
+## Execution backend (built-in tools routed into the sandbox)
+
+The `sandbox/` entry point uses the *same* sandbox differently: pi stays on the
+host and `bash`, `read`, `write`, `edit`, `grep`, `find`, `ls` plus the user's
+`!` commands execute **inside** it (see [sandbox/README.md](sandbox/README.md)).
+It protects a different thing, so it carries its own guarantees:
+
+1. **The host environment does not leak in.** pi's `bash` tool builds its child
+   environment from the *full* host environment, so forwarding it verbatim
+   would copy host API keys and tokens into the sandbox. Only `PI_*` session
+   metadata is forwarded (plus names listed in `DOCKER_SANDBOX_ENV_ALLOWLIST`),
+   and `DOCKER_*`/`COMPOSE_*` can never be allowlisted. Covered by a test.
+2. **The agent's file access is confined to the sandbox.** Because the file
+   tools are overridden, not just the shell, an absolute path resolves inside
+   the sandbox — no built-in tool can read or write a host path outside the
+   mounted workspace.
+3. **No shell-injection surface.** Paths and file bodies are passed as
+   *positional* arguments to `sh -c`, never spliced into the script text, so a
+   path cannot be reinterpreted as shell syntax or as a CLI option.
+4. **`grep` is reimplemented over the transport.** pi's grep tool spawns host
+   ripgrep regardless of custom operations; the backend walks and matches
+   in-sandbox instead, so a search cannot silently read host files.
+
+What this mode does **not** do:
+
+- **It does not confine pi's own process.** Extension tools other than these
+  built-in overrides still run on the host (subagents, `webshot`, ...). This is
+  a sandbox for the tools, not a wrapper around pi.
+- The sandbox has network access per its sbx network policy, and its own `/etc`,
+  `/usr` and so on are readable by the agent.
+- Killing the `sbx`/`docker` CLI on abort does not necessarily kill a process
+  already running inside the VM.
+
 ## Live verification: `docker_verify`
 
 The `docker_verify` tool runs a runtime audit of the sandbox and reports
@@ -115,3 +164,6 @@ sandboxes are never touched.
   level as any agent tooling writing to the workspace.
 - `sbx` port forwarding binds `127.0.0.1` on the host; apps inside the sandbox
   are not reachable from the LAN unless the host user forwards further.
+- `docker_curl` is confined to ports the sandbox itself published (it reads the
+  live `sbx ports` mappings and rejects any other host-localhost port), so it
+  cannot be used to probe unrelated host services on localhost.

package/template/Dockerfile

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1
+#
+# Lightweight sandbox baseline — the docker-buildable form of install.sh.
+#
+# The sbx snapshot itself is built by template/build.sh (which runs the same
+# install.sh inside a sandbox and `sbx template save`s the result). This
+# Dockerfile exists so the recipe can be BUILT AND MEASURED anywhere docker
+# runs, including CI and machines where sbx cannot start:
+#
+#   docker build -f template/Dockerfile -t sbx-lite .
+#   docker images sbx-lite --format '{{.Size}}'
+#
+# It is also a perfectly good sandbox image on its own for the docker backend of
+# the sandbox extension (SBX_BACKEND=docker).
+#
+# Ubuntu, because an sbx sandbox is always Ubuntu; using anything else here
+# would make the measured size unrepresentative of the real template.
+
+FROM ubuntu:24.04
+
+ARG NODE_VERSION=22.22.1
+ARG SBX_LITE_BUILD=on
+ARG SBX_LITE_PNPM=on
+ENV NODE_VERSION=${NODE_VERSION} \
+    SBX_LITE_BUILD=${SBX_LITE_BUILD} \
+    SBX_LITE_PNPM=${SBX_LITE_PNPM} \
+    LANG=C.UTF-8
+
+# Context is the repository root (see the build command above), so this path is
+# repo-relative rather than relative to this Dockerfile.
+COPY template/install.sh /tmp/install.sh
+RUN bash /tmp/install.sh && rm -f /tmp/install.sh
+
+WORKDIR /workspace