@coryrylan/cradle 0.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## [1.2.0](https://github.com/coryrylan/cradle/compare/cradle-v1.1.0...cradle-v1.2.0) (2026-07-26)
+
+### Features
+
+* **cli:** enhance sandbox configuration with docker support ([542cd79](https://github.com/coryrylan/cradle/commit/542cd79445cfc275ca8fa49f9b8e046a4fb23c9e))
+
+### Bug Fixes
+
+* **cli:** rename start command to run and update related documentation ([7324f82](https://github.com/coryrylan/cradle/commit/7324f823ad821b25e7d8e3db07b6cb585acfdd4e))
+
+## [1.1.0](https://github.com/coryrylan/cradle/compare/cradle-v1.0.1...cradle-v1.1.0) (2026-07-20)
+
+### Features
+
+* **cli:** enhance sandbox configuration for agent-browser ([363e4b1](https://github.com/coryrylan/cradle/commit/363e4b1b8b7896001ac459c9c508f8a1176868e2))
+
+## [1.0.1](https://github.com/coryrylan/cradle/compare/cradle-v1.0.0...cradle-v1.0.1) (2026-07-19)
+
+### Bug Fixes
+
+* **cli:** update agent folder specifications to include system.md ([52f8aa9](https://github.com/coryrylan/cradle/commit/52f8aa9a1aad73d34baf58f647b4ecbedf0dfd5a))
+
+## 1.0.0 (2026-07-19)
+
+### Features
+
+* init ([74684ae](https://github.com/coryrylan/cradle/commit/74684ae89643d062d906e1c9d311501ab18b6db6))
+
+### Bug Fixes
+
+* **cli:** mise cache paths ([a13f78b](https://github.com/coryrylan/cradle/commit/a13f78b9f65f427ee982bbcb78fa9f1335e285af))
+
 # Changelog
 
 ## 0.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 ![CI Build](https://github.com/coryrylan/cradle/actions/workflows/pull-request.yml/badge.svg)
 
-A runtime for portable agents defined as folders. `cradle start <dir>` reads an agent folder — an `APPEND_SYSTEM.md` plus optional pi-native config, skills, extensions, and sandbox posture — and launches the [pi](https://github.com/earendil-works/pi-mono) coding agent configured from it. An agent declaring `sandbox/nono.json` runs inside the [nono](https://github.com/always-further/nono) filesystem sandbox. See [ARCHITECTURE.md](../../ARCHITECTURE.md) for the folder format and [`examples/hello`](../../examples/hello) for a minimal agent. Built with Bun and TypeScript; install the standalone binary via `install.sh` (primary) or the npm package [`@coryrylan/cradle`](https://www.npmjs.com/package/@coryrylan/cradle) (alternative).
+A runtime for portable agents defined as folders. `cradle run <dir>` reads an agent folder — a `SYSTEM.md` or `APPEND_SYSTEM.md` (at least one) plus optional pi-native config, skills, extensions, and sandbox posture — and launches the [pi](https://github.com/earendil-works/pi-mono) coding agent configured from it. An agent declaring `sandbox/nono.json` or `sandbox/sbx.json` runs sandboxed — inside the [nono](https://github.com/always-further/nono) filesystem sandbox or the [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) microVM, respectively. See [ARCHITECTURE.md](../../ARCHITECTURE.md) for the folder format and [`examples/hello`](../../examples/hello) for a minimal agent. Built with Bun and TypeScript; install the standalone binary via `install.sh` (primary) or the npm package [`@coryrylan/cradle`](https://www.npmjs.com/package/@coryrylan/cradle) (alternative).
 
 ## Dependencies
 
@@ -10,8 +10,9 @@ A runtime for portable agents defined as folders. `cradle start <dir>` reads an
 
 | Tool                                              | Status          | Why                                                                                                                                                                                                                                                  |
 | ------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`pi`](https://github.com/earendil-works/pi-mono) | **Required**    | The coding agent cradle launches. Every `cradle start` spawns it.                                                                                                                                                                                    |
-| [`nono`](https://github.com/always-further/nono)  | **Recommended** | The filesystem sandbox pi runs inside for a sandboxed run — a folder declaring `sandbox/nono.json`, or `--sandbox`/`--offline`/`--allow-host`; required for that run, not needed otherwise.                                                          |
+| [`pi`](https://github.com/earendil-works/pi-mono) | **Required**    | The coding agent cradle launches. Every `cradle run` spawns it.                                                                                                                                                                                      |
+| [`nono`](https://github.com/always-further/nono)  | **Recommended** | The filesystem sandbox pi runs inside for a nono-backend run — a folder declaring `sandbox/nono.json`, or `--sandbox`/`--sandbox-backend nono`/`--offline`/`--allow-host` with no `sandbox/sbx.json`; required for that run, not needed otherwise.   |
+| [`sbx`](https://docs.docker.com/ai/sandboxes/)    | **Recommended** | The Docker Sandboxes microVM pi runs inside for an sbx-backend run — a folder declaring `sandbox/sbx.json`, or `--sandbox-backend sbx`; required for that run, not needed otherwise.                                                                 |
 | [`mise`](https://mise.jdx.dev)                    | **Recommended** | The supported way to install and manage `pi` and `nono`. cradle doesn't invoke mise directly, but it falls back to mise's shims when resolving the tools, and the generated sandbox profile grants mise's trees so a sandboxed pi finds its runtime. |
 
 ## Installation
@@ -53,32 +54,32 @@ bun start
 | `bun run test`            | Run tests (no coverage)                                         |
 | `bun run test:coverage`   | Run tests with coverage; enforces thresholds from `bunfig.toml` |
 | `bun run lint`            | Lint this package with ESLint (typescript-eslint strict)        |
-| `bun run format`          | Check formatting with Prettier                                  |
-| `bun run format:fix`      | Auto-fix formatting                                             |
 | `bun run ci`              | Run lint + build + test:coverage (used in CI)                   |
+| `bun run ci:nocache`      | Clean `dist/` then run `ci` (useful for cache debugging)        |
 | `bun run install:local`   | Build and install binary to `~/.local/bin`                      |
 | `bun run uninstall:local` | Remove locally installed binary                                 |
 
-> Knip (unused files / deps / exports) is configured at the monorepo root and runs across all workspaces. From the repo root, run `bun run lint:knip`.
+> Formatting (Prettier) and Knip (unused files / deps / exports) run at the monorepo root, not per-package. From the repo root: `bun run format` / `bun run format:fix` and `bun run lint:knip`.
 
 ## CLI Usage
 
 ```bash
 cradle --version
-cradle doctor                         # check pi (required), nono/mise (recommended) on PATH, with versions
-cradle start ./my-agent               # run an agent folder with pi; sandboxed when sandbox/nono.json exists
-cradle start my-agent                 # run a name from ~/.cradle/settings.json instead of a path
-cradle start . --offline              # block all outbound network (exfil protection)
-cradle start . --allow-host api.z.ai  # restrict network to these hosts (repeatable)
-cradle start . --no-sandbox           # run pi directly (debug)
-cradle start . --dry-run -- --resume  # print the write plan + command; forward `--resume` to pi
+cradle doctor                         # check pi (required), nono/sbx/mise (recommended) on PATH, with versions
+cradle run ./my-agent               # run an agent folder with pi; sandboxed when sandbox/nono.json or sandbox/sbx.json exists
+cradle run my-agent                 # run a name from ~/.cradle/settings.json instead of a path
+cradle run . --offline              # block all outbound network (exfil protection)
+cradle run . --allow-host api.example.com  # restrict network to these hosts (repeatable)
+cradle run . --sandbox-backend sbx  # run under the sbx Docker Sandboxes microVM instead of nono
+cradle run . --no-sandbox           # run pi directly (debug)
+cradle run . --dry-run -- --resume  # print the write plan + command; forward `--resume` to pi
 ```
 
 The agent runs in _your_ working directory; the agent folder is a parameter (default `.`). Everything after `--` is forwarded verbatim to pi. `--dry-run` prints the generated-extension write plan and the composed command without spawning (and without requiring the bins to be installed). Per-agent state (generated extensions + session history) lives under `~/.cradle/agents/<name>-<hash>/`.
 
 ### Global agent aliases (`~/.cradle/settings.json`)
 
-The `dir` positional accepts a bare name instead of a path — `cradle start my-agent` resolves against a global name → folder map, so agent folders you keep far from any project don't need a full path from every cwd:
+The `dir` positional accepts a bare name instead of a path — `cradle run my-agent` resolves against a global name → folder map, so agent folders you keep far from any project don't need a full path from every cwd:
 
 ```json
 {
@@ -90,7 +91,9 @@ The `dir` positional accepts a bare name instead of a path — `cradle start my-
 
 A bare name (no `/`, not `.`/`~`-led) checks the alias table first, falling back to the cwd-relative path (`./my-agent`) when no alias is defined — anything already path-shaped (`./x`, `../x`, `/abs/x`, `~/x`, `.`) is never looked up as an alias. See [ARCHITECTURE.md](../../ARCHITECTURE.md#global-agent-aliases) for the full resolution rules.
 
-Each sandboxed run generates its own nono profile at `~/.cradle/agents/<id>/nono-profile.json` — the built-in base merged with that agent's `sandbox/nono.json` grants — and points `nono run --profile` at it. There's no shared global profile and no separate setup step: an agent's whole sandbox posture lives in its own directory. To widen it (e.g. granting a tool's data dir), add a `sandbox/` folder to the agent with a `nono.json`:
+An agent folder can declare a sandbox posture for either backend: `sandbox/nono.json` (the OS-policy sandbox — covered in this section) or `sandbox/sbx.json` (the Docker Sandboxes microVM — see [Docker Sandboxes backend](#docker-sandboxes-backend-sandboxsbxjson) below), or both. `--sandbox-backend <nono|sbx>` picks the backend explicitly and forces it on; bare `--sandbox` uses whichever backend the folder declares, defaulting to nono, and nono wins when a folder declares both (with a warning naming `--sandbox-backend sbx` as the override).
+
+Each sandboxed nono run generates its own profile at `~/.cradle/agents/<id>/nono-profile.json` — the built-in base merged with that agent's `sandbox/nono.json` grants — and points `nono run --profile` at it. There's no shared global profile and no separate setup step: an agent's whole sandbox posture lives in its own directory. To widen it (e.g. granting a tool's data dir), add a `sandbox/` folder to the agent with a `nono.json`:
 
 ```json
 {
@@ -108,20 +111,20 @@ Outbound network is **open by default within a sandboxed run**. A `network` bloc
 {
   "network": {
     "block": false,
-    "allow_domain": ["api.z.ai", "localhost"],
+    "allow_domain": ["api.example.com", "localhost"],
     "open_port": [11434],
     "listen_port": [8080]
   }
 }
 ```
 
-| Key               | Effect                                                                                          |
-| ----------------- | ----------------------------------------------------------------------------------------------- |
-| `block`           | `true` denies **all** outbound (full offline).                                                  |
-| `allow_domain`    | Host allowlist. **Presence flips nono to default-deny** — unlisted hosts are refused (403).     |
-| `open_port`       | localhost TCP ports the agent may connect/bind (e.g. a local model or dev server).              |
-| `listen_port`     | TCP ports the agent may listen on.                                                              |
-| `network_profile` | Named nono network-policy profile (opaque pass-through; requires a host `network-policy.json`). |
+| Key               | Effect                                                                                           |
+| ----------------- | ------------------------------------------------------------------------------------------------ |
+| `block`           | `true` denies **all** outbound (full offline).                                                   |
+| `allow_domain`    | Host allowlist. **Presence flips nono to default-deny** — unlisted hosts are refused (403).      |
+| `open_port`       | localhost TCP ports the agent may connect/bind; `0` allows any outbound localhost port on macOS. |
+| `listen_port`     | TCP ports the agent may listen on.                                                               |
+| `network_profile` | Named nono network-policy profile (opaque pass-through; requires a host `network-policy.json`).  |
 
 An `allow_domain` allowlist blocks localhost too, so a local-model agent must list `localhost`/`127.0.0.1` **and** open its port (see [`examples/hello`](../../examples/hello), locked to Ollama on `localhost:11434`). CLI flags override the folder: `--offline` (full block) and repeatable `--allow-host <host>` (allowlist). Precedence: `--offline` > `--allow-host` > `sandbox/nono.json` > open. Requesting a network policy only means something inside the sandbox, so `--offline`/`--allow-host` force the sandbox on (same as `--sandbox`) unless `--no-sandbox` is passed explicitly, in which case cradle warns `network policy has no effect without the sandbox — pi runs with no network isolation (--sandbox to enforce it)` and nothing is enforced. cradle doesn't echo the resolved posture itself — run with `--verbose` to drop nono's `--silent` flag and see its own capabilities banner (grants + network mode), or read the generated per-agent profile (`nono-profile.json` in the agent's state dir). nono **fails closed** — a malformed `network` key or a platform that can't enforce proxy filtering makes the run refuse to start rather than silently ship an unenforced allowlist.
 
@@ -129,35 +132,58 @@ An `allow_domain` allowlist blocks localhost too, so a local-model agent must li
 
 Some tools need OS capabilities the conservative base profile denies. `sandbox/nono.json` can append raw macOS Seatbelt rules — s-expressions merged verbatim after the base's rules (nono validates the syntax at load). Each one widens the OS sandbox, so audit them where they live: the folder's `sandbox/nono.json` or the generated per-agent profile (`nono-profile.json` in the agent's state dir) — nono's own capabilities banner (shown with `--verbose`) never lists seatbelt rules. Ignored on Linux.
 
-**Browser automation is the motivating case.** [agent-browser](https://agent-browser.dev/) + Chrome for Testing runs sandboxed under nono with exactly two rules plus Chrome's own `--no-sandbox` flag:
+**Browser automation is the motivating case.** [agent-browser](https://agent-browser.dev/) + Chrome for Testing runs sandboxed under nono with a directory grant, a direct-child Unix socket grant, exactly two macOS rules, and Chrome's own `--no-sandbox` flag:
 
 ```json
 {
   "filesystem": {
-    "allow": ["~/.agent-browser"]
+    "allow": ["~/.agent-browser"],
+    "unix_socket_dir_bind": ["~/.agent-browser"]
+  },
+  "network": {
+    "open_port": [0]
   },
   "unsafe_macos_seatbelt_rules": ["(allow mach-register)", "(allow iokit-open)"]
 }
 ```
 
-| Entry                    | Why it's needed                                                                                                                                               |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `allow ~/.agent-browser` | agent-browser's own state dir — daemon socket, downloaded Chrome, config. Without it the daemon can't create its socket (`Operation not permitted`).          |
-| `(allow mach-register)`  | Chrome's Crashpad handler registers a Mach service (`bootstrap_check_in org.chromium.crashpad.*`); the base profile denies it, so the browser process aborts. |
-| `(allow iokit-open)`     | Chrome opens IOKit user clients during startup even headless; without it the browser process crashes before serving CDP.                                      |
+| Entry                                   | Why it's needed                                                                                                                                               |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allow ~/.agent-browser`                | agent-browser's state dir — downloaded Chrome, config, and daemon socket files.                                                                               |
+| `unix_socket_dir_bind ~/.agent-browser` | Lets the CLI and daemon connect to and bind direct-child Unix sockets; without it, `connect()` returns `EPERM`.                                               |
+| `open_port 0`                           | Lets the daemon connect to Chrome's random localhost DevTools port on macOS; without it, the CDP WebSocket returns `EPERM`.                                   |
+| `(allow mach-register)`                 | Chrome's Crashpad handler registers a Mach service (`bootstrap_check_in org.chromium.crashpad.*`); the base profile denies it, so the browser process aborts. |
+| `(allow iokit-open)`                    | Chrome opens IOKit user clients during startup even headless; without it the browser process crashes before serving CDP.                                      |
+
+`unix_socket_dir_bind` is non-recursive. Point it only at a dedicated socket directory, never a broad parent such as `~` or `/tmp`. Port `0` is nono's macOS-only outbound localhost wildcard; Linux requires explicit ports. The two macOS rules are IPC/IOKit capabilities only — the filesystem and network boundaries stay intact, so the sandbox still denies an ungranted path (verified: a granted read succeeds, `~/some-secret` returns `Operation not permitted`). No grant for Chrome's own `~/Library/…/Chrome for Testing` dir is needed — its Crashpad-database `stat` failure under the sandbox is non-fatal noise.
 
-The two rules are IPC/IOKit capabilities only — the filesystem and network boundaries stay intact, so the sandbox still denies an ungranted path (verified: a granted read succeeds, `~/some-secret` returns `Operation not permitted`). No grant for Chrome's own `~/Library/…/Chrome for Testing` dir is needed — its Crashpad-database `stat` failure under the sandbox is non-fatal noise.
+Chrome's **own** nested sandbox can't initialize inside nono's seatbelt (macOS forbids nesting), so its child processes need `--no-sandbox`. On every sandboxed run, cradle generates and loads `agent-browser-nono-fallback.ts` before package and agent extensions. On macOS it appends `--no-sandbox` to `AGENT_BROWSER_ARGS`; on every platform it maps nono's dynamically injected `HTTPS_PROXY`/`HTTP_PROXY` to `AGENT_BROWSER_PROXY`. Explicit agent-browser proxy configuration still wins. Unsandboxed runs do not load the fallback, so Chrome keeps its own sandbox. See [`examples/browser`](../../examples/browser) for the complete folder.
 
-Chrome's **own** nested sandbox can't initialize inside nono's seatbelt (macOS forbids nesting), so its child processes need `--no-sandbox`. Deliver it through a pi extension rather than a shell env var — an extension travels with the agent folder and pi propagates it into every tool's env regardless of how the extension itself set it. The simplest is a one-line agent extension:
+An agent that still cannot run sandboxed can declare `{ "sandbox": false }` in either sandbox file to opt that backend out. cradle then runs pi bare, warns loudly on every run, and an explicit `--sandbox`/`--sandbox-backend` flag always forces isolation back on.
 
-```ts
-// extensions/browser-sandbox.ts — set the flag before agent-browser launches Chrome
-process.env.AGENT_BROWSER_ARGS ??= '--no-sandbox';
+### Docker Sandboxes backend (`sandbox/sbx.json`)
+
+A folder can opt into the [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) (`sbx`) microVM instead of (or alongside) nono by declaring `sandbox/sbx.json` — a sibling file with a restricted subset of `sandbox/nono.json`'s schema: `sandbox: false` to opt out, `filesystem` `read`/`write`/`allow` only, `network` `block`/`allow_domain` only. Keys with no VM-boundary equivalent — `unix_socket_dir_bind`, `network_profile`, `open_port`, `listen_port`, `unsafe_macos_seatbelt_rules` — are warned and dropped rather than silently accepted. Force it explicitly with `--sandbox-backend sbx`; see [ARCHITECTURE.md](../../ARCHITECTURE.md#sandboxsbxjson) for the full schema, backend precedence, and run model.
+
+```json
+{
+  "network": { "allow_domain": ["api.example.com"] },
+  "filesystem": {
+    "allow": ["~/scratch"]
+  }
+}
 ```
 
-(Or pass `agent-browser --args --no-sandbox` on each call.) See [`examples/browser`](../../examples/browser) for the complete folder.
+An sbx run mounts your cwd (rw), the agent folder (ro), the state dir (rw), and `~/.pi/agent` (rw, so a host `pi login` and its OAuth refreshes carry over) into a sandbox named `cradle-<agentId>-<hash8>` — the hash keys the mount set, so a changed grant gets a fresh sandbox rather than attaching to stale mounts (clean those up with `sbx rm`). cradle then provisions `@earendil-works/pi-coding-agent` in-guest, pinned to the host's own `pi` version, and runs `sbx exec` with your host paths preserved verbatim, so the composed pi command is identical to a nono or unsandboxed run.
+
+Network policy differs from nono's: `block: true` denies all outbound; `allow_domain` allows the listed hosts (expanded to cover subdomains, with `localhost`/`127.0.0.1` rewritten to `host.docker.internal` — guest loopback is the microVM itself, not the host). Unlike nono's proxy, a per-sandbox `allow` rule only **adds** to your machine's global `sbx` policy and cannot subtract from it — cradle warns on every allowlist run. For strict, nono-style allowlist semantics, run `sbx policy init deny-all` once. One-time machine setup before the first sandboxed `sbx` run:
+
+```bash
+sbx login
+sbx policy init deny-all   # or allow-all / balanced — see sbx's own docs
+```
 
-An agent that still cannot run sandboxed can declare `{ "sandbox": false }` instead. cradle then runs pi bare, warns loudly on every run, and an explicit `--sandbox` flag always forces isolation back on.
+`cradle doctor` checks `sbx` alongside `pi`/`nono`/`mise`.
 
 ## Build Targets
 

package/dist/agent/aliases.d.ts

@@ -3,11 +3,11 @@ export interface ResolveRefDeps {
     readonly cwd: string;
 }
 /**
- * Resolve a `cradle start` ref into a folder path `loadAgentFolder` can load.
+ * Resolve a `cradle run` ref into a folder path `loadAgentFolder` can load.
  * Path-shaped refs pass through untouched (`loadAgentFolder`'s own `resolve()`
  * handles them, and they never consult `deps.cwd`); a bare name resolves
  * against the global alias table into an ABSOLUTE, normalized path, falling
- * back to the cwd-relative folder when no alias matches (so `cradle start
+ * back to the cwd-relative folder when no alias matches (so `cradle run
  * hello` from `examples/` keeps working) — and throwing only when neither
  * resolves. Every bare-name branch resolves against the injected `deps.cwd`,
  * never `process.cwd()`, so the dep is the single source of truth for what the

package/dist/agent/extensions/agent-browser-nono-fallback.d.ts

@@ -0,0 +1,3 @@
+export declare const AGENT_BROWSER_NONO_FALLBACK_EXTENSION_FILE = "agent-browser-nono-fallback.ts";
+/** Emit the sandbox-only environment bridge agent-browser needs when launched as a pi subprocess. */
+export declare function emitAgentBrowserNonoFallbackExtension(): string;

package/dist/agent/extensions/providers.d.ts

@@ -1 +1,12 @@
-export declare function emitProvidersExtension(providersJson: string): string;
+/** Options for `emitProvidersExtension` — see `commands/run.ts`'s `emitExtensionFiles`, the single call site. */
+export interface ProvidersEmitOptions {
+    /**
+     * Rewrite `localhost`/`127.0.0.1` provider baseUrls to the sbx host gateway
+     * (see `sbx/compose.ts`'s `rewriteLocalhostBaseUrl`): guest loopback is the
+     * microVM itself, so a host-bound local-model endpoint is unreachable under
+     * its own name inside the sbx backend. Off (byte-identical output) for nono
+     * and unsandboxed runs.
+     */
+    readonly rewriteLocalhostBaseUrls?: boolean;
+}
+export declare function emitProvidersExtension(providersJson: string, options?: ProvidersEmitOptions): string;

package/dist/agent/folder.d.ts

@@ -16,6 +16,8 @@ export interface AgentSandboxGrants {
     readonly read: readonly string[];
     readonly write: readonly string[];
     readonly allow: readonly string[];
+    /** Direct-child Unix socket paths the process may connect to and bind. */
+    readonly unixSocketDirBind: readonly string[];
 }
 /**
  * The agent's declared network posture — a curated subset of nono's profile
@@ -40,11 +42,20 @@ export interface AgentNetwork {
     readonly listenPort?: readonly number[];
 }
 export type AgentSandboxPosture = 'unconfigured' | 'enabled' | 'disabled';
+/**
+ * The sandbox enforcement backend a folder can declare a posture for: `nono`
+ * (Seatbelt/bubblewrap, `sandbox/nono.json`) or `sbx` (Docker Sandboxes
+ * microVM, `sandbox/sbx.json`). Backend resolution — which one actually runs
+ * — is a `commands/run.ts` concern; this module only reads each file's
+ * declared posture.
+ */
+export type SandboxBackend = 'nono' | 'sbx';
 export interface AgentSandbox {
     /**
-     * The folder's declared sandbox posture. `'unconfigured'` when the folder has
-     * no `sandbox/nono.json`; otherwise mirrors the file's `sandbox` key
-     * (absent ⇒ `'enabled'`).
+     * The declaring file's sandbox posture. `'unconfigured'` when the folder
+     * has no `sandbox/nono.json` (for the `sandbox` field) or no
+     * `sandbox/sbx.json` (for the `sbx` field); otherwise mirrors the file's
+     * `sandbox` key (absent ⇒ `'enabled'`).
      */
     readonly posture: AgentSandboxPosture;
     readonly network?: AgentNetwork;
@@ -62,15 +73,30 @@ export interface AgentSandbox {
 }
 export interface AgentFolder {
     readonly dir: string;
-    /** Abs path of APPEND_SYSTEM.md — appended to pi's system prompt via `--append-system-prompt`. */
-    readonly appendSystemFilePath: string;
+    /**
+     * Abs path of SYSTEM.md — REPLACES pi's default system prompt via
+     * `--system-prompt`; `null` when the folder has no SYSTEM.md. `loadAgentFolder`
+     * guarantees at least one of `systemFilePath`/`appendSystemFilePath` is non-null.
+     */
+    readonly systemFilePath: string | null;
+    /** Abs path of APPEND_SYSTEM.md — appended to pi's system prompt via `--append-system-prompt`; `null` when absent. */
+    readonly appendSystemFilePath: string | null;
     readonly settings: AgentSettings;
     /** Serialized `providers` object from models.json, `null` when absent. */
     readonly providersJson: string | null;
     readonly skillsDir: string | null;
     /** pi-native extensions (top-level `extensions/*.ts` plus each subdir's `index.ts`), absolute paths. */
     readonly extensionFiles: readonly string[];
+    /** `sandbox/nono.json`'s declared posture — the Seatbelt/bubblewrap backend. */
     readonly sandbox: AgentSandbox;
+    /**
+     * `sandbox/sbx.json`'s declared posture — the Docker Sandboxes microVM
+     * backend. A restricted subset of nono's schema: no Unix-socket grants, no
+     * named network-profile pass-through, no Seatbelt escape hatch — the VM
+     * boundary has no equivalent for them, so those keys are warned-and-dropped
+     * rather than silently accepted. See `readSbxSandbox`.
+     */
+    readonly sbx: AgentSandbox;
     readonly warnings: readonly string[];
 }
 export declare function loadAgentFolder(dir: string): Promise<AgentFolder>;

package/dist/agent/launch.d.ts

@@ -1,13 +1,13 @@
-import type { AgentFolder } from './folder.js';
+import type { AgentFolder, SandboxBackend } from './folder.js';
 export interface LaunchSpec {
     readonly folder: AgentFolder;
     readonly stateDir: string;
     /**
      * Where the generated providers extension is written (see
      * `folder.providersJson`) and where `--session-dir` points, sourced from the
-     * plan's own `extensionsDir`/`sessionsDir` (`commands/start.ts` — the single
+     * plan's own `extensionsDir`/`sessionsDir` (`commands/run.ts` — the single
      * derivation site; re-deriving from `stateDir` here risks silently
-     * disagreeing with a plan whose dirs were overridden after `planStart`).
+     * disagreeing with a plan whose dirs were overridden after `planRun`).
      */
     readonly extensionsDir: string;
     readonly sessionsDir: string;
@@ -16,21 +16,30 @@ export interface LaunchSpec {
      * from the plan's `statePaths` derivation like `extensionsDir`/`sessionsDir`.
      */
     readonly miseCacheDir: string;
-    readonly sandbox: boolean;
+    /**
+     * Which sandbox backend wraps this run, or `null` for unsandboxed. `'nono'`
+     * wraps the argv here — see `composeArgv`. `'sbx'` does NOT wrap here: its
+     * `sbx exec` wrapper is composed at materialization in `commands/run.ts`,
+     * so `composeArgv` returns the bare pi argv for both `'sbx'` and `null`.
+     * For `'sbx'`, `piBin` is the literal `pi` — resolved on the guest's PATH,
+     * since host paths (mise-shim included) are meaningless inside the
+     * microVM.
+     */
+    readonly backend: SandboxBackend | null;
     readonly passthrough: readonly string[];
     /** Resolved path, or bare `nono` for dry-run previews. */
     readonly nonoBin: string;
     /**
      * Resolved path (mise-shim fallback included, see `util/which.ts`), or bare
      * `pi` for dry-run previews. Used consistently whether or not the run is
-     * sandboxed — the generated profile already grants read on the mise install
-     * tree (see `nono/cradle-pi.json`), so the absolute path resolves inside the
-     * sandbox too; a bare `pi` only resolves on whatever PATH the spawning
-     * process happens to have, which is exactly the gap a fresh mise-only
-     * install falls into.
+     * nono-sandboxed — the generated profile already grants read on the mise
+     * install tree (see `nono/cradle-pi.json`), so the absolute path resolves
+     * inside the sandbox too; a bare `pi` only resolves on whatever PATH the
+     * spawning process happens to have, which is exactly the gap a fresh
+     * mise-only install falls into. See `backend` for the `'sbx'` exception.
      */
     readonly piBin: string;
-    /** Abs path of the generated per-agent nono profile; used only when `sandbox` is true. */
+    /** Abs path of the generated per-agent nono profile; used only when `backend` is `'nono'`. */
     readonly profilePath: string;
     /**
      * When true, nono runs without `--silent` so its capabilities banner
@@ -41,7 +50,7 @@ export interface LaunchSpec {
     /**
      * Abs paths of the pi extension entry files resolved from settings.json's
      * `packages` (see `./packages.js`), installed into `<stateDir>/npm` by
-     * `commands/start.ts`. Absent/empty on the argv-only preview used for
+     * `commands/run.ts`. Absent/empty on the argv-only preview used for
      * `--dry-run` (packages resolve at install time, after the preview is
      * printed) and on folders that declare no packages.
      */
@@ -50,15 +59,16 @@ export interface LaunchSpec {
 /**
  * Build the bare pi argv. `passthrough` lands last so user-passed flags win
  * under pi's last-wins parsing. The `-e` order is load-bearing: the generated
- * providers extension goes first, then the resolved package entries, then the
- * agent's own `extensions/` files — which load with the agent's providers
- * registered and any package-provided tools already available, since the
- * agent's own extensions may depend on them.
+ * providers extension goes first, followed by the nono-only agent-browser
+ * host-socket fallback, the resolved package entries, then the agent's own
+ * `extensions/` files — which load with the agent's providers registered,
+ * nono subprocess compatibility configured, and any package-provided tools
+ * already available, since the agent's own extensions may depend on them.
  */
 export declare function composePiArgv(spec: LaunchSpec): string[];
 /**
- * Compose the spawn env for a sandboxed run: `{ MISE_CACHE_DIR: spec.miseCacheDir }`;
- * `{}` when unsandboxed.
+ * Compose the spawn env for a nono-sandboxed run: `{ MISE_CACHE_DIR: spec.miseCacheDir }`;
+ * `{}` for `'sbx'` and unsandboxed runs alike.
  *
  * The generated profile denies the shared `~/Library/Caches/mise` on purpose
  * — a poisoned `bin_paths` cache would redirect which binaries the user's
@@ -68,9 +78,11 @@ export declare function composePiArgv(spec: LaunchSpec): string[];
  * at a private cache inside the already-granted state dir instead lets mise
  * cache writes succeed (no warnings, working cache) while the shared host
  * cache stays untouched; mise creates the directory itself, cradle never
- * pre-creates or wipes it. Unsandboxed runs return `{}` and keep the shared
+ * pre-creates or wipes it. Unsandboxed runs produce `{}` and keep the shared
  * host cache — no override needed since there's no sandbox denial to work
- * around.
+ * around; the sbx guest has no mise at all, and its HOME override rides the
+ * `sbx exec` argv composed in `commands/run.ts` rather than env, so the
+ * argv-only rule holds there too.
  *
  * This deliberately overrides any user-set `MISE_CACHE_DIR` for sandboxed
  * runs — the profile wouldn't grant a custom location either, so honoring one
@@ -84,8 +96,10 @@ export declare function composePiArgv(spec: LaunchSpec): string[];
  */
 export declare function composeEnv(spec: LaunchSpec): Record<string, string>;
 /**
- * Build the argv for `nono run … -- pi …`, or the bare pi argv when
- * sandboxing is disabled (`--no-sandbox`).
+ * Build the argv for `nono run … -- pi …` when `spec.backend` is `'nono'`, or
+ * the bare pi argv otherwise (`'sbx'` or `null`) — the `'sbx'` backend's own
+ * `sbx exec` wrapper is composed later, at materialization in
+ * `commands/run.ts`, not here (see `LaunchSpec.backend`).
  *
  * All filesystem grants (cwd, agent dir, state dir, and the agent's own
  * `sandbox/nono.json` entries) AND the network posture live inside the

package/dist/commands/doctor.d.ts

@@ -9,14 +9,13 @@ export interface DoctorCheck {
 }
 interface DoctorDeps {
     readonly which?: WhichFn;
-    /** Read a bin's `--version` output; injected so in-process tests never spawn. */
-    readonly readVersion?: (binPath: string) => Promise<string | null>;
+    /** Read a bin's version output (default argv `--version`; sbx passes `['version']`); injected so in-process tests never spawn. */
+    readonly readVersion?: (binPath: string, args?: readonly string[]) => Promise<string | null>;
 }
 /**
- * Probe the environment cradle depends on: `pi` (always required), `nono`
- * (required for sandboxed runs — a folder declaring sandbox/nono.json, or
- * --sandbox/--offline/--allow-host; not needed otherwise), and `mise`
- * (recommended toolchain manager).
+ * Probe the environment cradle depends on: `pi` (always required), `nono` and
+ * `sbx` (each required only for runs on its backend — see the notes), and
+ * `mise` (recommended toolchain manager).
  */
 export declare function runDoctor(deps?: DoctorDeps): Promise<DoctorCheck[]>;
 export declare function formatDoctorReport(checks: readonly DoctorCheck[]): string;

package/dist/commands/{start.d.ts → run.d.ts}

@@ -1,8 +1,10 @@
+import { type SandboxBackend } from '../agent/folder.js';
 import { type LaunchSpec } from '../agent/launch.js';
 import { type NpmPackageSpec } from '../agent/packages.js';
+import { type SbxSpec } from '../sbx/compose.js';
 import { type TreeFile } from '../setup/install.js';
 import { type WhichFn } from '../util/which.js';
-export interface StartFlags {
+export interface RunFlags {
     readonly dir: string;
     /** `--offline` → full network block. Overrides the folder network posture and forces the sandbox on (unless --no-sandbox). */
     readonly offline?: boolean;
@@ -10,15 +12,19 @@ export interface StartFlags {
     readonly allowHost?: readonly string[];
     /** Explicit CLI choice: `--no-sandbox` → true, `--sandbox` → false. Absent = defer to the folder. */
     readonly noSandbox?: boolean;
+    /** `--sandbox-backend` → explicit backend choice; implies the sandbox is on (still beaten by `--no-sandbox`). */
+    readonly sandboxBackend?: SandboxBackend;
     readonly dryRun?: boolean;
     readonly passthrough?: readonly string[];
     /** `--verbose` → show nono's full sandbox capabilities banner instead of the one-line status. */
     readonly verbose?: boolean;
 }
-interface StartDeps {
+interface RunDeps {
     readonly cwd?: string;
     readonly home?: string;
     readonly which?: WhichFn;
+    /** Whether stdout is a TTY (`cli.ts` passes `process.stdout.isTTY`) — rides the sbx exec argv as `-t`; default false. */
+    readonly tty?: boolean;
 }
 /**
  * The agent's settings.json `packages` resolved into a per-agent npm install
@@ -41,27 +47,46 @@ export interface PackagesPlan {
      */
     readonly installCommand: readonly string[];
 }
-export interface StartPlan {
+/**
+ * The sbx backend's materialization plan: the setup argvs `materializeRun`
+ * runs before the final `sbx exec` (composed there, wrapping the pi argv).
+ * `spec.piVersion` is null at plan time — the provision argv is recomposed at
+ * materialize with the host pi version (see `MaterializeDeps.readPiVersion`)
+ * so the guest install pins to it; the plan-time argv is the unpinned preview
+ * dry-run prints, the same precedent as package `-e` entries, which also
+ * resolve at materialize.
+ */
+export interface SbxRunPlan {
+    readonly spec: SbxSpec;
+    /** Resolved host pi path — the version-pin source for guest provisioning; never spawned in-guest. */
+    readonly hostPiBin: string;
+    readonly createArgv: readonly string[];
+    readonly policyArgvs: ReadonlyArray<readonly string[]>;
+    readonly provisionArgv: readonly string[];
+}
+export interface RunPlan {
     /** Generated extensions, relative to `extensionsDir`. */
     readonly files: readonly TreeFile[];
     /**
      * Authoritative — the single derivation site for where generated extensions
-     * and sessions live. `materializeStart` re-asserts these onto `launch`
+     * and sessions live. `materializeRun` re-asserts these onto `launch`
      * before composing the final argv, so overriding either here (as tests do)
      * changes the composed argv accordingly instead of silently disagreeing
-     * with whatever `launch` had baked in at `planStart` time.
+     * with whatever `launch` had baked in at `planRun` time.
      */
     readonly extensionsDir: string;
     readonly sessionsDir: string;
     readonly warnings: readonly string[];
-    /** The generated per-agent nono profile to write before spawning; `null` on unsandboxed runs (no profile needed). */
+    /** The generated per-agent nono profile to write before spawning; `null` unless the resolved backend is `'nono'`. */
     readonly profile: {
         readonly path: string;
         readonly content: string;
     } | null;
+    /** The sbx setup plan (see `SbxRunPlan`); `null` unless the resolved backend is `'sbx'`. */
+    readonly sbx: SbxRunPlan | null;
     /** Settings.json `packages` resolved into an install plan; `null` when the folder declares none. */
     readonly packages: PackagesPlan | null;
-    /** The single argv source: `composeArgv(plan.launch)` — package-entry-free until `materializeStart` recomposes it with resolved package entries. */
+    /** The single argv source: `composeArgv(plan.launch)` — package-entry-free until `materializeRun` recomposes it with resolved package entries. */
     readonly launch: LaunchSpec;
     readonly dryRun: boolean;
 }
@@ -71,23 +96,32 @@ export interface StartPlan {
  * decides whether to print it (`--dry-run`) or materialize + spawn it.
  *
  * `--dry-run` only previews, so it deliberately skips the bin checks — you can
- * compose a command before nono/pi are installed.
+ * compose a command before nono/sbx/pi are installed.
  */
-export declare function planStart(flags: StartFlags, deps?: StartDeps): Promise<StartPlan>;
+export declare function planRun(flags: RunFlags, deps?: RunDeps): Promise<RunPlan>;
+export interface SbxRunResult {
+    readonly exitCode: number;
+    readonly stderr: string;
+}
 export interface MaterializeDeps {
     /** Runs a package install (e.g. `npm install`) in `cwd`; `cli.ts` always passes `runInstall` from `util/proc.js`. */
     readonly install?: (command: readonly string[], cwd: string) => Promise<void>;
+    /** Runs one sbx setup command (create/policy/provision), capturing stderr; `cli.ts` passes `runCapture` from `util/proc.js`. */
+    readonly run?: (argv: readonly string[]) => Promise<SbxRunResult>;
+    /** Reads the host pi version (`cli.ts` passes its `--version` reader) to pin the guest install; absent → unpinned provisioning. */
+    readonly readPiVersion?: (piBin: string) => Promise<string | null>;
 }
 /**
  * Write the generated extensions (replacing stale ones), ensure the sessions
- * dir, and — on sandboxed runs — (re)write the generated per-agent nono profile
- * that `nono run --profile` points at. When the folder declares `packages`,
- * also (re)install the per-agent npm project and resolve each package's pi
- * extension entries, returning the final argv with those entries appended as
- * `-e` flags plus any resolution warnings; otherwise the plan's argv is
- * already final.
+ * dir, and — per backend — (re)write the generated per-agent nono profile
+ * that `nono run --profile` points at, or run the sbx setup sequence
+ * (create/policy/provision) and wrap the final argv in `sbx exec`. When the
+ * folder declares `packages`, also (re)install the per-agent npm project and
+ * resolve each package's pi extension entries, returning the final argv with
+ * those entries appended as `-e` flags plus any resolution warnings;
+ * otherwise the plan's argv is already final.
  */
-export declare function materializeStart(plan: StartPlan, deps?: MaterializeDeps): Promise<{
+export declare function materializeRun(plan: RunPlan, deps?: MaterializeDeps): Promise<{
     argv: string[];
     warnings: string[];
 }>;