@sandbar-sdk/cli 0.3.0 → 0.5.0

package/README.md

@@ -29,6 +29,8 @@ The adapter package must be installed where the CLI can find it: in `~/.config/s
 | `exec <sandbox> [--cwd] [--env K=V] [--stdin \| --stdin-file] [--timeout] [--max-output] -- cmd...` | Run argv; exit code passes through |
 | `sh <sandbox> '<script>'` (or `-- '<script>'`) | Run a shell script; same flags as exec |
 | `run [create and exec flags] [--keep] -- cmd...` | Create, run one command, destroy |
+| `image build <oci-ref> [--name] [--refresh]` | Build an OCI image on a provider that needs a build first, and record it |
+| `image ls`, `image inspect <name>`, `image forget <name>` | List, show or drop image records; `forget` lists what the provider still holds |
 | `cp <src> <dst>` | Copy one file; one side is `<sandbox>:/path` |
 | `cat <sandbox>:/path` | Print a file |
 | `doctor` | Check config, credentials and the connection; creates nothing |
@@ -49,7 +51,7 @@ With `--json` (or `SANDBAR_JSON=1`) stdout holds exactly one document: `{"ok":tr
 | 1 | other failure (including a taken `--name` or an existing `cp --no-clobber` target) |
 | 2 | usage error |
 | 3 | not found |
-| 4 | unsupported, adapter or password-manager CLI not installed, or `limits.maxSandboxes` reached |
+| 4 | unsupported, adapter missing (`ADAPTER_NOT_INSTALLED`) or failing to load (`ADAPTER_LOAD_FAILED`), password-manager CLI not installed, or `limits.maxSandboxes` reached |
 | 5 | authentication or permission, including a password-manager secret that cannot be read |
 | 6 | outcome unknown: an effect may have happened, inspect before retrying |
 | 7 | retryable before any effect (rate limit, capacity, unavailable) |
@@ -67,7 +69,7 @@ source <(sandbar completion bash)   # add to ~/.bashrc
 sandbar completion fish > ~/.config/fish/completions/sandbar.fish
 ```
 
-Completion covers commands, flags, `--provider` ids, `--profile` names from `sandbar.json`, and sandbox names for `exec`, `sh`, `inspect`, `rm`, `cp` and `cat`. Sandbox names come from the local store, so pressing tab never calls a provider.
+Completion covers commands, flags, `--provider` ids, `--profile` names from `sandbar.json`, sandbox names for `exec`, `sh`, `inspect`, `rm`, `cp` and `cat`, and image record names for `image inspect` and `image forget`. Sandbox names come from the local store, so pressing tab never calls a provider.
 
 ## Agent skill
 
@@ -91,7 +93,7 @@ The CLI carries an agent skill that matches its own version. `sandbar skill` pri
 
 - Profile selection: `--profile`, `SANDBAR_PROFILE`, `--provider`, `SANDBAR_PROVIDER`, then `default`.
 - `provider` names an official adapter (`@sandbar-sdk/<provider>`); `config` and `credentials` are that adapter's own settings. `module` and `export` load any adapter, either a definition or a bound adapter.
-- Credentials can be written in the profile directly, as `env:NAME` references, or as password-manager references (below). Keep the file private (`chmod 600`) if it holds keys. Env-only providers read `DAYTONA_API_KEY` and `DAYTONA_TARGET`; `E2B_API_KEY`; `BOXD_API_KEY`, `BOXD_ORG` and `BOXD_NETWORK=internet` (boxd always allows egress, so its adapter requires choosing it); `VERCEL_TOKEN`, `VERCEL_TEAM_ID` and `VERCEL_PROJECT_ID`; `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET`, `MODAL_APP_NAME` and `MODAL_ENVIRONMENT`.
+- Credentials can be written in the profile directly, as `env:NAME` references, or as password-manager references (below). Keep the file private (`chmod 600`) if it holds keys. Env-only providers read `DAYTONA_API_KEY` and `DAYTONA_TARGET`; `E2B_API_KEY`; `BOXD_API_KEY`, `BOXD_ORG` and `BOXD_NETWORK=internet` (boxd always allows egress, so its adapter requires choosing it); `BOAT_API_KEY` and `BOAT_NETWORK=internet` (likewise for Boat); `VERCEL_TOKEN`, `VERCEL_TEAM_ID` and `VERCEL_PROJECT_ID`; `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET`, `MODAL_APP_NAME` and `MODAL_ENVIRONMENT`.
 - `limits.maxSandboxes` (or `SANDBAR_MAX_SANDBOXES`) caps how many sandboxes the store may hold. Unset means uncapped.
 
 ## Password managers
@@ -110,13 +112,30 @@ Any `config` or `credentials` value (including one that comes from a provider's
 
 If the tool is not installed the command exits 4 (`SECRET_TOOL_MISSING`); if it cannot read the secret it exits 5 (`SECRET_UNAVAILABLE`) with the tool's own message. Each reference is read at most once per command.
 
+## Images
+
+`--image` always takes an OCI reference, such as `python:3.12` or `ghcr.io/org/tool@sha256:...`. A provider-specific template or snapshot goes in the profile's `image` setting or `--prepared <id>`.
+
+- boxd and Modal boot the OCI image directly. Nothing is built or kept.
+- E2B and Daytona must build it into a prepared image first. A build is slow, may cost money, and leaves a provider-side template or snapshot behind that destroying a sandbox does not delete. So `create --image` and `run --image` only use a build already recorded for the same reference and profile; otherwise they fail with exit 4 before creating anything, naming the command to run:
+
+  ```sh
+  sandbar image build python:3.12 --provider e2b   # once
+  sandbar run --image python:3.12 --provider e2b -- python3 --version
+  ```
+
+  Pass `--build` to build a missing image during `create` or `run`, or set `"images": { "autoBuild": true }` in `sandbar.json` to always do so. Each reference is built once per profile either way.
+- Vercel takes neither and rejects `--image`.
+
+`sandbar image build` records the reference as typed, the profile, the prepared image (bound to the provider account that built it) and the provider-side resources it left. Running it again for a recorded reference does nothing unless you pass `--refresh`, which builds again, for example after a mutable tag such as `python:3.12` moved; pin a digest for an exact image. `image forget` removes the record and prints the resources the provider still holds; the CLI cannot delete them yet, so remove them with the provider's own tools when you no longer need them. A build whose outcome is unknown (exit 6) keeps its record, and `image inspect` asks the provider again how it ended. Providers do not report a resolved digest, so records do not have one.
+
 ## State store
 
-Sandbox references are kept as one JSON file per sandbox in `~/.config/sandbar/state/sandboxes/<name>.json` (override with `--state-dir` or `SANDBAR_STATE_DIR`, relative to the working directory, or `state.dir`, relative to the config file). Records hold references only, never credentials. A name is claimed before the provider call, so a crash or uncertain create leaves a record that `ls` shows. An uncertain create also keeps the SDK's recovery reference: `rm` and `inspect` use it to ask how the original request ended (never resending it) and `rm` destroys the sandbox if one was made; otherwise `rm --force` drops the record. Records are written whole (a temporary file linked or renamed into place) and updates take a short per-record lock, so concurrent CLI processes on one machine never see half-written files; `ls` skips an unreadable record with a warning. The `maxSandboxes` check is best effort under concurrent creates. The store sits behind a small per-record interface (create-if-absent, compare-and-swap update, paged list) so object storage can back it later.
+Sandbox references are kept as one JSON file per sandbox in `~/.config/sandbar/state/sandboxes/<name>.json`, and image records in `images/<name>.json` next to it (override with `--state-dir` or `SANDBAR_STATE_DIR`, relative to the working directory, or `state.dir`, relative to the config file). Records hold references only, never credentials. A name is claimed before the provider call, so a crash or uncertain create leaves a record that `ls` shows. An uncertain create also keeps the SDK's recovery reference: `rm` and `inspect` use it to ask how the original request ended (never resending it) and `rm` destroys the sandbox if one was made; otherwise `rm --force` drops the record. Records are written whole (a temporary file linked or renamed into place) and updates take a short per-record lock, so concurrent CLI processes on one machine never see half-written files; `ls` skips an unreadable record with a warning. The `maxSandboxes` check is best effort under concurrent creates. The store sits behind a small per-record interface (create-if-absent, compare-and-swap update, paged list) so object storage can back it later.
 
 ## Not yet
 
-Planned for later steps: `--lifetime`/`--idle`/`--port` create flags, recursive `cp`, detached processes and logs, preview URLs, suspend/resume/renew, `gc`, image builds and records, snapshots and volumes, `sandbar adapter add`, an S3-compatible store, KeePassXC and system-keyring references, and MCP mode. `--image` is passed to the adapter as an OCI image; providers that need a build first reject it before creating anything.
+Planned for later steps: `--lifetime`/`--idle`/`--port` create flags, recursive `cp`, detached processes and logs, preview URLs, suspend/resume/renew, `gc`, deleting built images (`image rm`), snapshots and volumes, `sandbar adapter add`, an S3-compatible store, KeePassXC and system-keyring references, and MCP mode.
 
 ## Development
 
@@ -125,3 +144,5 @@ Tests run the real CLI as a subprocess against the fake provider; they make no p
 ```sh
 bun test packages/cli
 ```
+
+Inside this repository the official adapters are development dependencies of the CLI, so `bun packages/cli/src/main.ts` finds them from any directory without an adapters install.

package/dist/main.js

@@ -5,7 +5,7 @@ import { parseArgs } from "node:util";
 // package.json
 var package_default = {
   name: "@sandbar-sdk/cli",
-  version: "0.3.0",
+  version: "0.5.0",
   private: false,
   type: "module",
   description: "Agent-first command line for creating and managing Sandbar sandboxes.",
@@ -30,6 +30,12 @@ var package_default = {
     zod: "4.6.5"
   },
   devDependencies: {
+    "@sandbar-sdk/boat": "workspace:*",
+    "@sandbar-sdk/boxd": "workspace:*",
+    "@sandbar-sdk/daytona": "workspace:*",
+    "@sandbar-sdk/e2b": "workspace:*",
+    "@sandbar-sdk/modal": "workspace:*",
+    "@sandbar-sdk/vercel": "workspace:*",
     "@sandbar/provider-fake": "workspace:*"
   },
   license: "Apache-2.0",
@@ -51,10 +57,10 @@ import { readFile as readFile4, stat as stat2, writeFile as writeFile2 } from "n
 import { basename, join as join4, resolve as resolve3 } from "node:path";
 import {
   AdapterSandbox,
-  Image,
+  Image as Image2,
   NonzeroExitError,
   ResourceReference as ResourceReference2,
-  SandbarError as SandbarError2
+  SandbarError as SandbarError3
 } from "sandbar-sdk";
 import { z as z4 } from "zod";
 
@@ -140,6 +146,7 @@ var managementExitCodes = new Map([
   ["NOT_FOUND", 3],
   ["UNSUPPORTED", 4],
   ["ADAPTER_NOT_INSTALLED", 4],
+  ["ADAPTER_LOAD_FAILED", 4],
   ["LIMIT_REACHED", 4],
   ["SECRET_TOOL_MISSING", 4],
   ["SECRET_UNAVAILABLE", 5],
@@ -308,15 +315,454 @@ function resolveEnvReferences(value, env, where) {
   return value;
 }
 
+// src/images.ts
+import { randomBytes as randomBytes2 } from "node:crypto";
+import {
+  Image,
+  SandbarError as SandbarError2
+} from "sandbar-sdk";
+
+// src/store.ts
+import { createHash, randomBytes } from "node:crypto";
+import { link, mkdir, readFile as readFile2, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { join as join2 } from "node:path";
+import { ResourceReference } from "sandbar-sdk";
+import { z as z2 } from "zod";
+var RecordName = z2.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
+var SandboxRecord = z2.strictObject({
+  format: z2.literal(1),
+  kind: z2.literal("sandbox"),
+  name: RecordName,
+  status: z2.enum(["creating", "created", "unknown"]),
+  profile: z2.string().min(1),
+  provider: z2.string().min(1),
+  createdAt: z2.iso.datetime({ offset: true }),
+  labels: z2.record(z2.string(), z2.string()),
+  image: z2.string().optional(),
+  reference: ResourceReference.extend({ kind: z2.literal("sandbox") }).nullable(),
+  recovery: z2.custom((value) => z2.record(z2.string(), z2.unknown()).safeParse(value).success).optional()
+});
+var RetainedResource = z2.strictObject({
+  kind: z2.string().min(1),
+  id: z2.string().min(1),
+  ownership: z2.enum(["verified", "unknown"]),
+  cleanup: z2.enum(["manual", "provider_expiry", "none_known"])
+});
+var ImageRecord = z2.strictObject({
+  format: z2.literal(1),
+  kind: z2.literal("image"),
+  name: RecordName,
+  status: z2.enum(["building", "built", "unknown"]),
+  profile: z2.string().min(1),
+  provider: z2.string().min(1),
+  createdAt: z2.iso.datetime({ offset: true }),
+  source: z2.string().min(1),
+  prepared: z2.strictObject({
+    kind: z2.literal("prepared"),
+    value: z2.string().min(1),
+    provider: z2.string().min(1),
+    scope: ResourceReference.shape.scope
+  }).nullable(),
+  retainedResources: z2.array(RetainedResource),
+  recovery: z2.custom((value) => z2.record(z2.string(), z2.unknown()).safeParse(value).success).optional()
+});
+var schemas = { sandbox: SandboxRecord, image: ImageRecord };
+var folders = { sandbox: "sandboxes", image: "images" };
+function errorCode(cause) {
+  return cause instanceof Error && "code" in cause ? String(cause.code) : undefined;
+}
+function versionOf(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+function encode(kind, record) {
+  return `${JSON.stringify(schemas[kind].parse(record), null, 2)}
+`;
+}
+var STALE_LOCK_MS = 30000;
+var sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+class FsStateStore {
+  dir;
+  constructor(dir) {
+    this.dir = dir;
+  }
+  folder(kind) {
+    return join2(this.dir, folders[kind]);
+  }
+  path(kind, name) {
+    return join2(this.folder(kind), `${RecordName.parse(name)}.json`);
+  }
+  async temporary(kind, name, text) {
+    await mkdir(this.folder(kind), { recursive: true });
+    const path = `${this.path(kind, name)}.${randomBytes(6).toString("hex")}.tmp`;
+    await writeFile(path, text, { flag: "wx" });
+    return path;
+  }
+  async locked(kind, name, action) {
+    const lock = `${this.path(kind, name)}.lock`;
+    await mkdir(this.folder(kind), { recursive: true });
+    for (let attempt = 0;; attempt++) {
+      try {
+        await writeFile(lock, String(process.pid), { flag: "wx" });
+        break;
+      } catch (cause) {
+        if (errorCode(cause) !== "EEXIST")
+          throw cause;
+        const held = await stat(lock).catch(() => null);
+        if (held && Date.now() - held.mtimeMs > STALE_LOCK_MS)
+          await unlink(lock).catch(() => {});
+        else if (attempt >= 100)
+          throw new CliError("CONFLICT", `Store record ${name} is locked by another process`);
+        else
+          await sleep(20);
+      }
+    }
+    try {
+      return await action();
+    } finally {
+      await unlink(lock).catch(() => {});
+    }
+  }
+  async get(kind, name) {
+    let text;
+    try {
+      text = await readFile2(this.path(kind, name), "utf8");
+    } catch (cause) {
+      if (errorCode(cause) === "ENOENT")
+        return null;
+      throw cause;
+    }
+    let json;
+    try {
+      json = z2.json().parse(JSON.parse(text));
+    } catch {
+      throw new CliError("STORE_INVALID", `Store record ${this.path(kind, name)} is not valid JSON`);
+    }
+    const parsed = schemas[kind].safeParse(json);
+    if (!parsed.success)
+      throw new CliError("STORE_INVALID", `Store record ${this.path(kind, name)} is invalid`);
+    return { record: parsed.data, version: versionOf(text) };
+  }
+  async create(kind, name, record) {
+    const text = encode(kind, record);
+    const temporary = await this.temporary(kind, name, text);
+    try {
+      await link(temporary, this.path(kind, name));
+    } catch (cause) {
+      if (errorCode(cause) === "EEXIST")
+        throw new CliError("CONFLICT", `Name ${name} is already in use`);
+      throw cause;
+    } finally {
+      await unlink(temporary).catch(() => {});
+    }
+    return { version: versionOf(text) };
+  }
+  async update(kind, name, record, version) {
+    return this.locked(kind, name, async () => {
+      const current = await this.get(kind, name);
+      if (!current || current.version !== version)
+        throw new CliError("CONFLICT", `Store record ${name} changed concurrently`);
+      const text = encode(kind, record);
+      await rename(await this.temporary(kind, name, text), this.path(kind, name));
+      return { version: versionOf(text) };
+    });
+  }
+  async remove(kind, name, version) {
+    await this.locked(kind, name, async () => {
+      if (version !== undefined) {
+        const current = await this.get(kind, name);
+        if (current && current.version !== version)
+          throw new CliError("CONFLICT", `Store record ${name} changed concurrently`);
+      }
+      try {
+        await unlink(this.path(kind, name));
+      } catch (cause) {
+        if (errorCode(cause) !== "ENOENT")
+          throw cause;
+      }
+    });
+  }
+  async list(kind, cursor, limit = 1000) {
+    let files;
+    try {
+      files = await readdir(this.folder(kind));
+    } catch (cause) {
+      if (errorCode(cause) === "ENOENT")
+        return { names: [] };
+      throw cause;
+    }
+    const names = files.filter((file) => file.endsWith(".json")).map((file) => file.slice(0, -5)).filter((name) => RecordName.safeParse(name).success && (!cursor || name > cursor)).sort();
+    const page = names.slice(0, limit);
+    return { names: page, cursor: names.length > limit ? page.at(-1) : undefined };
+  }
+}
+async function listAll(store, kind, onInvalid) {
+  const found = [];
+  let cursor;
+  do {
+    const page = await store.list(kind, cursor);
+    for (const name of page.names) {
+      try {
+        const entry = await store.get(kind, name);
+        if (entry)
+          found.push(entry);
+      } catch (cause) {
+        if (!(cause instanceof CliError) || cause.code !== "STORE_INVALID")
+          throw cause;
+        onInvalid?.(`warning: ${cause.message}; skipped`);
+      }
+    }
+    cursor = page.cursor;
+  } while (cursor);
+  return found;
+}
+function checkName(name) {
+  const parsed = RecordName.safeParse(name);
+  if (!parsed.success)
+    throw usage(`Invalid name ${name}`, "use 1-63 lowercase letters, digits and dashes, starting with a letter or digit");
+  return parsed.data;
+}
+function generatedName() {
+  return `sb-${randomBytes(3).toString("hex").slice(0, 5)}`;
+}
+
+// src/images.ts
+var BuildResult = ImageRecord.pick({ prepared: true, retainedResources: true }).extend({
+  prepared: ImageRecord.shape.prepared.unwrap()
+});
+function derivedName(source) {
+  const base = (source.split("/").at(-1) ?? source).toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 57).replace(/^-+|-+$/g, "");
+  return RecordName.safeParse(base).success ? base : "image";
+}
+async function findBuild(store, profile, source) {
+  const entries = await listAll(store, "image");
+  return entries.find(({ record }) => record.profile === profile && record.source === source && record.prepared);
+}
+function mergeRetained(previous, next) {
+  const seen = new Set(previous.map((item) => `${item.kind}/${item.id}`));
+  return [...previous, ...next.filter((item) => !seen.has(`${item.kind}/${item.id}`))];
+}
+async function claim(store, record, requested) {
+  const base = requested ? checkName(requested) : derivedName(record.source);
+  for (let attempt = 0;; attempt++) {
+    const name = attempt === 0 ? base : `${base}-${randomBytes2(2).toString("hex")}`;
+    const full = { ...record, name };
+    try {
+      const { version } = await store.create("image", name, full);
+      return { record: full, version };
+    } catch (cause) {
+      if (!(cause instanceof CliError) || cause.code !== "CONFLICT" || attempt >= 8)
+        throw cause;
+      if (requested)
+        throw new CliError("CONFLICT", `Image name ${name} is already in use`, "choose another --name, or `sandbar image forget` the old record");
+    }
+  }
+}
+async function buildImage(session, client, profile, source, options) {
+  const store = await session.store();
+  const existing = await findBuild(store, profile.name, source);
+  if (existing && options.name && existing.record.name !== checkName(options.name))
+    throw new CliError("CONFLICT", `${source} is already built for profile ${profile.name} as ${existing.record.name}`, "use that name, or `sandbar image forget` it first");
+  if (existing && !options.refresh)
+    return { entry: existing, built: false };
+  if (!(await client.capabilities()).imageBuild)
+    throw new CliError("UNSUPPORTED", `${profile.provider} does not build images`, "providers that boot OCI images directly take --image without a build");
+  const claimed = existing ?? await claim(store, {
+    format: 1,
+    kind: "image",
+    status: "building",
+    profile: profile.name,
+    provider: profile.provider,
+    createdAt: new Date().toISOString(),
+    source,
+    prepared: null,
+    retainedResources: []
+  }, options.name);
+  session.ctx.out.note(`building ${source} on ${profile.provider}; this can take a few minutes`);
+  let result;
+  try {
+    result = await client.images.build({ source: { kind: "oci", value: source } }, { signal: session.ctx.signal });
+  } catch (cause) {
+    const report = describeError(cause);
+    if (report.outcome === "rejected") {
+      if (!existing)
+        await store.remove("image", claimed.record.name, claimed.version);
+      throw cause;
+    }
+    const recovery = report.known?.recovery;
+    let kept = `the store keeps ${claimed.record.name}; \`sandbar image inspect ${claimed.record.name}\` checks the build again`;
+    if (existing)
+      kept = `${existing.record.name} still holds the previous build; the new one may exist on the provider`;
+    else
+      try {
+        await store.update("image", claimed.record.name, { ...claimed.record, status: "unknown", recovery }, claimed.version);
+      } catch (storeCause) {
+        kept = `the store could not record it (${describeError(storeCause).message}); keep the reference below`;
+      }
+    throw new CliError("OUTCOME_UNKNOWN", report.message, kept, {
+      image: claimed.record.name,
+      recovery
+    });
+  }
+  const { recovery: _recovery, ...rest } = claimed.record;
+  const record = {
+    ...rest,
+    status: "built",
+    createdAt: new Date().toISOString(),
+    prepared: result.prepared,
+    retainedResources: mergeRetained(claimed.record.retainedResources, result.retainedResources)
+  };
+  try {
+    const { version } = await store.update("image", record.name, record, claimed.version);
+    return { entry: { record, version }, built: true };
+  } catch (cause) {
+    throw new CliError("STORE_WRITE_FAILED", `Built ${source} as ${result.prepared.value} but could not record it: ${describeError(cause).message}`, "the provider keeps the image; pass it with --prepared, or rebuild once the store is writable", { image: record.name }, "partial");
+  }
+}
+async function imageEnvironment(session, client, profile, source, build) {
+  if (!(await client.capabilities()).imageBuild)
+    return Image.oci(source);
+  const store = await session.store();
+  const found = await findBuild(store, profile.name, source);
+  if (found?.record.prepared)
+    return Image.prepared(found.record.prepared);
+  const autoBuild = (await session.config()).value.images?.autoBuild === true;
+  if (!build && !autoBuild)
+    throw new CliError("UNSUPPORTED", `image ${source} is not built for profile ${profile.name}; run: sandbar image build ${source}`, `pass --build to build it during this command, or set images.autoBuild in sandbar.json`);
+  const { entry } = await buildImage(session, client, profile, source, {});
+  if (!entry.record.prepared)
+    throw new Error(`Image record ${entry.record.name} has no build`);
+  return Image.prepared(entry.record.prepared);
+}
+function summary(record) {
+  return {
+    name: record.name,
+    source: record.source,
+    profile: record.profile,
+    provider: record.provider,
+    status: record.status,
+    createdAt: record.createdAt,
+    prepared: record.prepared?.value ?? null,
+    retainedResources: record.retainedResources
+  };
+}
+function retainedLines(record) {
+  return record.retainedResources.map((item) => `  ${item.kind} ${item.id} (cleanup ${item.cleanup}, ownership ${item.ownership})`);
+}
+async function findImage(store, name) {
+  const found = await store.get("image", checkName(name));
+  if (!found)
+    throw new CliError("NOT_FOUND", `No image record named ${name}`, "list them with `sandbar image ls`");
+  return found;
+}
+async function recoverBuild(session, store, entry) {
+  const { record } = entry;
+  if (record.status !== "unknown" || record.recovery?.kind !== "image_build")
+    return entry;
+  const client = await session.connect(await session.profileNamed(record.profile));
+  let value;
+  try {
+    value = await (await client.recover(record.recovery)).observe();
+  } catch (cause) {
+    if (cause instanceof SandbarError2 && cause.effect !== "none")
+      return entry;
+    throw cause;
+  }
+  const parsed = BuildResult.safeParse(value);
+  if (!parsed.success)
+    return entry;
+  const { recovery: _recovery, ...rest } = record;
+  const recovered = { ...rest, status: "built", ...parsed.data };
+  const { version } = await store.update("image", record.name, recovered, entry.version);
+  session.ctx.out.note(`${record.name}: recovered the uncertain build as ${parsed.data.prepared.value}`);
+  return { record: recovered, version };
+}
+async function buildCommand(session, flags, args) {
+  if (args.length !== 1)
+    throw usage("Expected exactly one OCI image reference", "e.g. sandbar image build python:3.12");
+  const profile = await session.profile();
+  const client = await session.connect(profile);
+  const { entry, built } = await buildImage(session, client, profile, args[0], {
+    name: flags.string("name"),
+    refresh: flags.bool("refresh")
+  });
+  const { record } = entry;
+  session.ctx.out.success({ ...summary(record), built }, built ? record.name : `${record.name} (already built; pass --refresh to build ${record.source} again)`);
+  return 0;
+}
+async function lsImages(session) {
+  const store = await session.store();
+  const entries = await listAll(store, "image", (message) => session.ctx.out.note(message));
+  const rows = entries.map(({ record }) => summary(record));
+  const lines = rows.map((row) => [row.name.padEnd(20), row.profile.padEnd(12), row.status.padEnd(9), row.source].join(" "));
+  session.ctx.out.success({ images: rows }, rows.length ? [
+    `${"NAME".padEnd(20)} ${"PROFILE".padEnd(12)} ${"STATUS".padEnd(9)} SOURCE`,
+    ...lines
+  ].join(`
+`) : "no image records; build one with `sandbar image build <oci-ref>`");
+  return 0;
+}
+async function inspectImage(session, args) {
+  if (args.length !== 1)
+    throw usage("Expected exactly one image name");
+  const store = await session.store();
+  const { record } = await recoverBuild(session, store, await findImage(store, args[0]));
+  const lines = [
+    `name      ${record.name}`,
+    `source    ${record.source}`,
+    `provider  ${record.provider} (profile ${record.profile})`,
+    `status    ${record.status}`,
+    `prepared  ${record.prepared?.value ?? "none"}`,
+    `built     ${record.createdAt}`,
+    ...record.retainedResources.length ? ["retained", ...retainedLines(record)] : []
+  ];
+  session.ctx.out.success({ ...summary(record), preparedImage: record.prepared, recovery: record.recovery ?? null }, lines.join(`
+`));
+  return 0;
+}
+async function forgetImage(session, args) {
+  if (args.length !== 1)
+    throw usage("Expected exactly one image name");
+  const store = await session.store();
+  const { record, version } = await findImage(store, args[0]);
+  await store.remove("image", record.name, version);
+  const lines = [`forgot ${record.name}`];
+  if (record.retainedResources.length)
+    lines.push(`${record.provider} still holds these; delete them with the provider's own tools if you no longer need them:`, ...retainedLines(record));
+  session.ctx.out.success({ name: record.name, result: "forgotten", retainedResources: record.retainedResources }, lines.join(`
+`));
+  return 0;
+}
+var imageActions = ["build", "ls", "inspect", "forget"];
+async function imageCommand(session, flags) {
+  const [action, ...args] = flags.positionals;
+  if ((flags.string("name") || flags.bool("refresh")) && action !== "build")
+    throw usage("--name and --refresh only apply to `sandbar image build`");
+  switch (action) {
+    case "build":
+      return buildCommand(session, flags, args);
+    case "ls":
+      if (args.length)
+        throw usage("image ls takes no arguments");
+      return lsImages(session);
+    case "inspect":
+      return inspectImage(session, args);
+    case "forget":
+      return forgetImage(session, args);
+    default:
+      throw usage(action ? `Unknown image command ${action}` : "Expected an image command", `use one of: ${imageActions.join(", ")}`);
+  }
+}
+
 // src/providers.ts
-import { access, readFile as readFile2 } from "node:fs/promises";
-import { dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "node:path";
-import { pathToFileURL } from "node:url";
+import { access, readFile as readFile3 } from "node:fs/promises";
+import { dirname as dirname2, isAbsolute, join as join3, relative, resolve as resolve2 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import {
   bindAdapter
 } from "@sandbar-sdk/adapter";
 import { Sandbar } from "sandbar-sdk";
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var providers = [
   {
     id: "daytona",
@@ -345,6 +791,16 @@ var providers = [
       network: { env: "BOXD_NETWORK", required: true }
     }
   },
+  {
+    id: "boat",
+    module: "@sandbar-sdk/boat",
+    export: "boatAdapter",
+    experimental: true,
+    credentials: { apiKey: "BOAT_API_KEY" },
+    config: {
+      network: { env: "BOAT_NETWORK", required: true }
+    }
+  },
   {
     id: "vercel",
     module: "@sandbar-sdk/vercel",
@@ -412,7 +868,7 @@ function fromProfile(name, profile, loaded, env) {
     }),
     ...Object.entries(profile.credentials ?? {}).map(([key, value]) => [
       key,
-      z2.string().parse(resolveEnvReferences(value, env, `${where}.credentials.${key}`))
+      z3.string().parse(resolveEnvReferences(value, env, `${where}.credentials.${key}`))
     ])
   ]);
   const config = Object.fromEntries([
@@ -441,17 +897,9 @@ function fromProfile(name, profile, loaded, env) {
     credentials
   };
 }
-var ConditionalEntry = z2.object({
-  import: z2.string().optional(),
-  default: z2.string().optional()
-});
-var PackageManifest = z2.object({
-  main: z2.string().optional(),
-  exports: z2.union([
-    z2.string(),
-    z2.object({ ".": z2.union([z2.string(), ConditionalEntry]).optional() }),
-    ConditionalEntry
-  ]).optional()
+var PackageManifest = z3.object({
+  main: z3.string().optional(),
+  exports: z3.json().optional()
 });
 async function exists(path) {
   try {
@@ -461,24 +909,45 @@ async function exists(path) {
     return false;
   }
 }
-function rootEntry(manifest) {
-  const field = manifest.exports;
-  const plain = z2.string().safeParse(field);
+var importConditions = new Set(["import", "node", "default"]);
+function exportTarget(value) {
+  const plain = z3.string().safeParse(value);
   if (plain.success)
     return plain.data;
-  const dotted = z2.object({ ".": z2.union([z2.string(), ConditionalEntry]) }).safeParse(field);
-  const target = dotted.success ? dotted.data["."] : field;
-  const direct = z2.string().safeParse(target);
-  if (direct.success)
-    return direct.data;
-  const conditional = ConditionalEntry.safeParse(target);
-  return conditional.success && (conditional.data.import ?? conditional.data.default) || manifest.main || "index.js";
+  const list = z3.array(z3.json()).safeParse(value);
+  if (list.success) {
+    for (const item of list.data) {
+      const target = exportTarget(item);
+      if (target)
+        return target;
+    }
+    return null;
+  }
+  const conditions = z3.record(z3.string(), z3.json()).safeParse(value);
+  if (!conditions.success)
+    return null;
+  for (const [condition, nested] of Object.entries(conditions.data)) {
+    if (!importConditions.has(condition))
+      continue;
+    const target = exportTarget(nested);
+    if (target)
+      return target;
+  }
+  return null;
+}
+function rootEntry(manifest) {
+  const exports = manifest.exports;
+  if (exports === undefined || exports === null)
+    return manifest.main || "index.js";
+  const subpaths = z3.record(z3.string(), z3.json()).safeParse(exports);
+  const root = subpaths.success && Object.keys(subpaths.data).some((key) => key.startsWith(".")) ? subpaths.data["."] : exports;
+  return (root === undefined ? null : exportTarget(root)) ?? manifest.main ?? "index.js";
 }
 async function entryFor(packageDir) {
-  const manifestPath = join2(packageDir, "package.json");
+  const manifestPath = join3(packageDir, "package.json");
   if (!await exists(manifestPath))
     return null;
-  const manifest = PackageManifest.safeParse(JSON.parse(await readFile2(manifestPath, "utf8")));
+  const manifest = PackageManifest.safeParse(JSON.parse(await readFile3(manifestPath, "utf8")));
   if (!manifest.success)
     return null;
   const entry = resolve2(packageDir, rootEntry(manifest.data));
@@ -494,15 +963,15 @@ async function resolveAdapterModule(profile, cwd, env) {
     return pathToFileURL(resolve2(profile.baseDir, spec)).href;
   if (!PackageName.test(spec))
     throw usage(`Adapter module ${spec} is not a package name or a path`);
-  const roots = [join2(configHome(env), "adapters", "node_modules")];
+  const roots = [join3(configHome(env), "adapters", "node_modules")];
   if (profile.searchProject)
     for (let dir = resolve2(cwd);; dir = dirname2(dir)) {
-      roots.push(join2(dir, "node_modules"));
+      roots.push(join3(dir, "node_modules"));
       if (dirname2(dir) === dir)
         break;
     }
   for (const root of roots) {
-    const entry = await entryFor(join2(root, spec));
+    const entry = await entryFor(join3(root, spec));
     if (entry)
       return pathToFileURL(entry).href;
   }
@@ -511,16 +980,24 @@ async function resolveAdapterModule(profile, cwd, env) {
 function isAdapter(value) {
   return value instanceof Object && "name" in value && "connect" in value && "config" in value;
 }
-var AdapterExport = z2.custom(isAdapter);
+var AdapterExport = z3.custom(isAdapter);
+async function adapterMissing(target, spec, message) {
+  if (target.startsWith("file:"))
+    return !await exists(fileURLToPath(target));
+  return message.includes(`'${spec}'`) || message.includes(`"${spec}"`);
+}
 async function loadAdapter(profile, cwd, env, secrets) {
   const target = await resolveAdapterModule(profile, cwd, env);
-  const schema = z2.object({ [profile.export]: AdapterExport });
+  const schema = z3.object({ [profile.export]: AdapterExport });
   let parsed;
   try {
     parsed = schema.safeParse(await import(target));
   } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
     const official = descriptor(profile.provider);
-    throw new CliError("ADAPTER_NOT_INSTALLED", `Cannot load adapter ${profile.module} for profile ${profile.name}: ${cause instanceof Error ? cause.message : cause}`, official ? `install it into ${join2(configHome(env), "adapters")} (cd there && npm install ${official.module}); project installs need adapters.searchProject or SANDBAR_PROJECT_ADAPTERS=1` : "check the profile's module path");
+    if (await adapterMissing(target, profile.module, message))
+      throw new CliError("ADAPTER_NOT_INSTALLED", `Cannot load adapter ${profile.module} for profile ${profile.name}: ${message}`, official ? `install it into ${join3(configHome(env), "adapters")} (cd there && npm install ${official.module}); project installs need adapters.searchProject or SANDBAR_PROJECT_ADAPTERS=1` : "check the profile's module path");
+    throw new CliError("ADAPTER_LOAD_FAILED", `Adapter ${profile.module} for profile ${profile.name} is installed but failed to load: ${message}`, "reinstall the adapter and its dependencies; the message above comes from the adapter package");
   }
   if (!parsed.success)
     throw new CliError("ADAPTER_NOT_INSTALLED", `${profile.module} has no adapter export named ${profile.export}`);
@@ -531,191 +1008,13 @@ async function loadAdapter(profile, cwd, env, secrets) {
     return exported;
   const where = `profile ${profile.name}`;
   const config = await secrets.resolve(profile.config, `${where}.config`);
-  const credentials = z2.record(z2.string(), z2.string()).parse(await secrets.resolve(profile.credentials, `${where}.credentials`));
+  const credentials = z3.record(z3.string(), z3.string()).parse(await secrets.resolve(profile.credentials, `${where}.credentials`));
   return bindAdapter(exported, config, credentials);
 }
 async function connect(profile, cwd, env, secrets) {
   return Sandbar.connect(await loadAdapter(profile, cwd, env, secrets));
 }
 
-// src/store.ts
-import { createHash, randomBytes } from "node:crypto";
-import { link, mkdir, readFile as readFile3, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
-import { join as join3 } from "node:path";
-import { ResourceReference } from "sandbar-sdk";
-import { z as z3 } from "zod";
-var RecordName = z3.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
-var SandboxRecord = z3.strictObject({
-  format: z3.literal(1),
-  kind: z3.literal("sandbox"),
-  name: RecordName,
-  status: z3.enum(["creating", "created", "unknown"]),
-  profile: z3.string().min(1),
-  provider: z3.string().min(1),
-  createdAt: z3.iso.datetime({ offset: true }),
-  labels: z3.record(z3.string(), z3.string()),
-  image: z3.string().optional(),
-  reference: ResourceReference.extend({ kind: z3.literal("sandbox") }).nullable(),
-  recovery: z3.custom((value) => z3.record(z3.string(), z3.unknown()).safeParse(value).success).optional()
-});
-function errorCode(cause) {
-  return cause instanceof Error && "code" in cause ? String(cause.code) : undefined;
-}
-function versionOf(text) {
-  return createHash("sha256").update(text).digest("hex");
-}
-function encode(record) {
-  return `${JSON.stringify(SandboxRecord.parse(record), null, 2)}
-`;
-}
-var STALE_LOCK_MS = 30000;
-var sleep = (ms) => new Promise((done) => setTimeout(done, ms));
-
-class FsStateStore {
-  dir;
-  constructor(dir) {
-    this.dir = dir;
-  }
-  folder(kind) {
-    return join3(this.dir, `${kind}es`);
-  }
-  path(kind, name) {
-    return join3(this.folder(kind), `${RecordName.parse(name)}.json`);
-  }
-  async temporary(kind, name, text) {
-    await mkdir(this.folder(kind), { recursive: true });
-    const path = `${this.path(kind, name)}.${randomBytes(6).toString("hex")}.tmp`;
-    await writeFile(path, text, { flag: "wx" });
-    return path;
-  }
-  async locked(kind, name, action) {
-    const lock = `${this.path(kind, name)}.lock`;
-    await mkdir(this.folder(kind), { recursive: true });
-    for (let attempt = 0;; attempt++) {
-      try {
-        await writeFile(lock, String(process.pid), { flag: "wx" });
-        break;
-      } catch (cause) {
-        if (errorCode(cause) !== "EEXIST")
-          throw cause;
-        const held = await stat(lock).catch(() => null);
-        if (held && Date.now() - held.mtimeMs > STALE_LOCK_MS)
-          await unlink(lock).catch(() => {});
-        else if (attempt >= 100)
-          throw new CliError("CONFLICT", `Store record ${name} is locked by another process`);
-        else
-          await sleep(20);
-      }
-    }
-    try {
-      return await action();
-    } finally {
-      await unlink(lock).catch(() => {});
-    }
-  }
-  async get(kind, name) {
-    let text;
-    try {
-      text = await readFile3(this.path(kind, name), "utf8");
-    } catch (cause) {
-      if (errorCode(cause) === "ENOENT")
-        return null;
-      throw cause;
-    }
-    let json;
-    try {
-      json = z3.json().parse(JSON.parse(text));
-    } catch {
-      throw new CliError("STORE_INVALID", `Store record ${this.path(kind, name)} is not valid JSON`);
-    }
-    const parsed = SandboxRecord.safeParse(json);
-    if (!parsed.success)
-      throw new CliError("STORE_INVALID", `Store record ${this.path(kind, name)} is invalid`);
-    return { record: parsed.data, version: versionOf(text) };
-  }
-  async create(kind, name, record) {
-    const text = encode(record);
-    const temporary = await this.temporary(kind, name, text);
-    try {
-      await link(temporary, this.path(kind, name));
-    } catch (cause) {
-      if (errorCode(cause) === "EEXIST")
-        throw new CliError("CONFLICT", `Name ${name} is already in use`);
-      throw cause;
-    } finally {
-      await unlink(temporary).catch(() => {});
-    }
-    return { version: versionOf(text) };
-  }
-  async update(kind, name, record, version) {
-    return this.locked(kind, name, async () => {
-      const current = await this.get(kind, name);
-      if (!current || current.version !== version)
-        throw new CliError("CONFLICT", `Store record ${name} changed concurrently`);
-      const text = encode(record);
-      await rename(await this.temporary(kind, name, text), this.path(kind, name));
-      return { version: versionOf(text) };
-    });
-  }
-  async remove(kind, name, version) {
-    await this.locked(kind, name, async () => {
-      if (version !== undefined) {
-        const current = await this.get(kind, name);
-        if (current && current.version !== version)
-          throw new CliError("CONFLICT", `Store record ${name} changed concurrently`);
-      }
-      try {
-        await unlink(this.path(kind, name));
-      } catch (cause) {
-        if (errorCode(cause) !== "ENOENT")
-          throw cause;
-      }
-    });
-  }
-  async list(kind, cursor, limit = 1000) {
-    let files;
-    try {
-      files = await readdir(this.folder(kind));
-    } catch (cause) {
-      if (errorCode(cause) === "ENOENT")
-        return { names: [] };
-      throw cause;
-    }
-    const names = files.filter((file) => file.endsWith(".json")).map((file) => file.slice(0, -5)).filter((name) => RecordName.safeParse(name).success && (!cursor || name > cursor)).sort();
-    const page = names.slice(0, limit);
-    return { names: page, cursor: names.length > limit ? page.at(-1) : undefined };
-  }
-}
-async function listAll(store, kind, onInvalid) {
-  const found = [];
-  let cursor;
-  do {
-    const page = await store.list(kind, cursor);
-    for (const name of page.names) {
-      try {
-        const entry = await store.get(kind, name);
-        if (entry)
-          found.push(entry);
-      } catch (cause) {
-        if (!(cause instanceof CliError) || cause.code !== "STORE_INVALID")
-          throw cause;
-        onInvalid?.(`warning: ${cause.message}; skipped`);
-      }
-    }
-    cursor = page.cursor;
-  } while (cursor);
-  return found;
-}
-function checkName(name) {
-  const parsed = RecordName.safeParse(name);
-  if (!parsed.success)
-    throw usage(`Invalid name ${name}`, "use 1-63 lowercase letters, digits and dashes, starting with a letter or digit");
-  return parsed.data;
-}
-function generatedName() {
-  return `sb-${randomBytes(3).toString("hex").slice(0, 5)}`;
-}
-
 // src/units.ts
 var durationUnits = new Map([
   ["", 1],
@@ -777,9 +1076,10 @@ class Flags {
 function createRequest(flags) {
   if (flags.string("image") && flags.string("prepared"))
     throw usage("Pass either --image or --prepared, not both");
-  if (flags.bool("build"))
-    throw usage("--build is not available yet", "build images in a later CLI release; for now use a prepared image or a provider that boots OCI images directly");
+  if (flags.bool("build") && !flags.string("image"))
+    throw usage("--build needs --image");
   return {
+    build: flags.bool("build"),
     name: flags.string("name"),
     ifNotExists: flags.bool("if-not-exists"),
     image: flags.string("image"),
@@ -790,7 +1090,7 @@ function createRequest(flags) {
 }
 function createInput(request) {
   return {
-    environment: request.image ? Image.oci(request.image) : request.prepared ? Image.prepared(request.prepared) : undefined,
+    environment: request.prepared ? Image2.prepared(request.prepared) : undefined,
     network: request.network,
     labels: Object.keys(request.labels).length ? request.labels : undefined
   };
@@ -824,7 +1124,7 @@ async function createSandbox(session, request) {
         const box2 = await session.reopen(current.record, client2);
         return { client: client2, box: box2, ...current, existing: true };
       } catch (cause) {
-        if (!(cause instanceof SandbarError2) || cause.code !== "NOT_FOUND")
+        if (!(cause instanceof SandbarError3) || cause.code !== "NOT_FOUND")
           throw cause;
         await store.remove("sandbox", current.record.name, current.version);
       }
@@ -848,10 +1148,12 @@ async function createSandbox(session, request) {
   const input = createInput(request);
   try {
     client = await session.connect(profile);
+    if (request.image)
+      input.environment = await imageEnvironment(session, client, profile, request.image, request.build);
     if (input.environment) {
       const plan = await client.sandboxes.checkCreate(input);
       if (plan.status === "unsupported" || plan.status === "unavailable")
-        throw new CliError("UNSUPPORTED", `${profile.provider} cannot create this sandbox: ${plan.reason}`, request.image ? "this provider may need the image built first (sandbar image build arrives in a later release), or use --prepared with a provider image" : undefined);
+        throw new CliError("UNSUPPORTED", `${profile.provider} cannot create this sandbox: ${plan.reason}`, request.image ? "use --prepared with a provider image instead" : undefined);
     }
   } catch (cause) {
     await store.remove("sandbox", claimed.record.name, claimed.version);
@@ -956,9 +1258,9 @@ async function stateOf(session, record, client) {
     const box = await session.reopen(record, client);
     return (await box.inspect({ signal: session.ctx.signal })).state;
   } catch (cause) {
-    if (cause instanceof SandbarError2 && cause.code === "NOT_FOUND")
+    if (cause instanceof SandbarError3 && cause.code === "NOT_FOUND")
       return "gone";
-    if (cause instanceof SandbarError2 && cause.code === "UNSUPPORTED")
+    if (cause instanceof SandbarError3 && cause.code === "UNSUPPORTED")
       return "unknown";
     return "unreachable";
   }
@@ -1059,7 +1361,7 @@ async function recoverCreate(session, store, target) {
   try {
     value = await (await client.recover(record.recovery)).observe();
   } catch (cause) {
-    if (cause instanceof SandbarError2 && cause.effect !== "none")
+    if (cause instanceof SandbarError3 && cause.effect !== "none")
       return target;
     throw cause;
   }
@@ -1098,7 +1400,7 @@ async function removeOne(session, store, found, force, all) {
   try {
     box = await session.reopen(record);
   } catch (cause) {
-    if (!(cause instanceof SandbarError2) || cause.code !== "NOT_FOUND")
+    if (!(cause instanceof SandbarError3) || cause.code !== "NOT_FOUND")
       throw cause;
     await forget(store, target);
     return { kind: "removed", item: { name: record.name, result: "gone", retainedResources: [] } };
@@ -1584,7 +1886,7 @@ import { homedir as homedir2 } from "node:os";
 import { dirname as dirname3, join as join5 } from "node:path";
 
 // ../../skills/sandbar-cli/SKILL.md
-var SKILL_default = "---\nname: sandbar-cli\ndescription: Create, use and clean up cloud sandboxes from the shell with the `sandbar` CLI (Daytona, E2B, boxd, Vercel, Modal). Use when you need an isolated machine to run untrusted or generated code, try a build or test in a clean environment, or manage sandboxes someone created with sandbar; prefer it over provider-specific CLIs.\n---\n\n# Use sandboxes with the sandbar CLI\n\n`sandbar` creates and manages sandboxes on any Sandbar provider. It is built for agents: it never prompts, every command has a stable `--json` form, and exit codes tell you what to do next.\n\n## Check the setup first\n\n```sh\nsandbar doctor --json      # config, credentials, provider connection; creates nothing\nsandbar providers --json   # which adapters are installed and which credentials are missing\n```\n\n- If `sandbar` is not on PATH, stop and tell the user; do not install anything yourself.\n- The provider comes from `--profile`, `SANDBAR_PROFILE`, `--provider`, `SANDBAR_PROVIDER`, then `default` in `~/.config/sandbar/sandbar.json`. Do not edit that file or credentials unless the user asks.\n- A missing adapter (exit 4, `ADAPTER_NOT_INSTALLED`) or missing credential (exit 2) is the user's to fix. Report the `hint` from the error.\n\n**Sandboxes cost money.** Create only what the task needs and destroy it when done.\n\n## Always use JSON\n\nPass `--json` (or set `SANDBAR_JSON=1`). stdout then holds exactly one document:\n\n```json\n{\"ok\": true, \"data\": {...}}\n{\"ok\": false, \"error\": {\"code\": \"...\", \"message\": \"...\", \"retryable\": false, \"outcome\": \"rejected\", \"hint\": \"...\", \"known\": {...}}}\n```\n\nDiagnostics go to stderr. Read `error.hint` before deciding what to do.\n\n## One-shot work: `run`\n\n`run` creates a sandbox, runs one command and always destroys it. Prefer it whenever you do not need the sandbox afterwards.\n\n```sh\nsandbar run --json -- python3 -c 'print(2 + 2)'\nsandbar run --json --prepared base --timeout 5m -- sh -c 'pip install -q requests && python3 app.py'\n```\n\nPass the command after `--` as separate arguments. Its data is `{exitCode, stdout, stderr, truncated, sandbox}`, where `sandbox` names the sandbox it created and destroyed.\n\n## Longer work: create, use, remove\n\n```sh\nsandbar create --json --name job-1 --prepared base   # prints the name; reuse it everywhere\nsandbar cp ./app.py job-1:/home/user/app.py\nsandbar exec --json job-1 --cwd /home/user -- python3 app.py\nsandbar sh --json job-1 'cd /home/user && ls -la | head'\nsandbar cat job-1:/home/user/out.txt\nsandbar rm --json job-1\n```\n\n- Give sandboxes a `--name` so you can find them again; names are lowercase letters, digits and dashes. `--if-not-exists` reuses a live sandbox with that name instead of failing.\n- `exec` takes an argv after `--`; no shell runs. Use `sh` only when you need pipes, redirects or `&&`. For a script that starts with `-`, put it after `--`: `sandbar sh job-1 -- '-n ...'`.\n- `--env K=V` (repeatable), `--cwd`, `--stdin` or `--stdin-file <path>`, `--timeout 30s|5m|1h`, `--max-output 1m`.\n- `cp` copies one file; one side is `<sandbox>:/absolute/path`. `--no-clobber` refuses to overwrite.\n- `--image <oci-ref>` boots an OCI image where the provider supports it; `--prepared <id>` uses a provider template or snapshot. On providers that need an image built first, `--image` fails with exit 4 before creating anything.\n- `sandbar ls --json` lists known sandboxes with their live state (`running`, `gone`, `unreachable`, ...). `sandbar inspect --json <name>` shows state, expiry and the saved reference.\n\nAlways `rm` what you created before finishing, even after failures. `rm` only destroys sandboxes this CLI created; never pass `--force` or `rm --all` unless the user asked.\n\n## Exit codes\n\n`exec`, `sh` and `run` exit with the **remote command's** exit code. Their own failures always exit **125**, with the error in the JSON document. A command that ran but reported no exit status is 125 with `OUTCOME_UNKNOWN`; its output is in `error.known.exec`. It is never success.\n\nOther commands:\n\n| Code | Meaning                                                           | What to do                                           |\n| ---- | ----------------------------------------------------------------- | ---------------------------------------------------- |\n| 0    | success                                                           |                                                      |\n| 1    | other failure, including a name already taken                     | read the message                                     |\n| 2    | usage or local error                                              | fix the command; `sandbar <command> --help`          |\n| 3    | not found                                                         | `sandbar ls`                                         |\n| 4    | unsupported, adapter or tool not installed, limit reached         | tell the user; do not work around it                 |\n| 5    | authentication, permission, or unreadable password-manager secret | tell the user                                        |\n| 6    | **outcome unknown**: the effect may have happened                 | **do not retry**; run `sandbar ls` / `inspect` first |\n| 7    | retryable (rate limit, capacity, unavailable) before any effect   | wait, then retry once or twice                       |\n| 8    | partial: some steps happened                                      | read `error.known` and `error.details`               |\n\n## When things go wrong\n\n- **Never repeat a create after exit 6 or `outcome: \"unknown\"`.** The store keeps the name in status `unknown`; check `sandbar ls --json`. `sandbar rm <name>` first asks the provider how that create ended (never resending it) and destroys the sandbox if one exists. If it still exits 4 because the outcome is unknown, and the user agrees it is gone, `sandbar rm --force <name>` drops the record.\n- **`run` exits 125 with `CLEANUP_FAILED`**: the command result is in `error.known.exec`, but the sandbox is still running. Tell the user and run the `rm` from the hint.\n- **`rm` exits 8**: `error.details` lists what was `removed`, `skipped` and `failed`. Retry only the failed names once the cause is fixed.\n- **`STORE_WRITE_FAILED`**: the sandbox exists but was not recorded. The reference is in `error.known.reference`; save it to a file and destroy with `sandbar rm @file.json`.\n- Interrupting `run` (Ctrl-C, SIGTERM) still destroys its sandbox and exits 130 (143 for SIGTERM) with `INTERRUPTED`. A second signal exits immediately and may leave it running.\n\n## Discover more\n\n`sandbar schema` prints every command, flag and exit code as JSON. `sandbar <command> --help` shows usage and examples.\n";
+var SKILL_default = "---\nname: sandbar-cli\ndescription: Create, use and clean up cloud sandboxes from the shell with the `sandbar` CLI (Daytona, E2B, boxd, Boat, Vercel, Modal). Use when you need an isolated machine to run untrusted or generated code, try a build or test in a clean environment, or manage sandboxes someone created with sandbar; prefer it over provider-specific CLIs.\n---\n\n# Use sandboxes with the sandbar CLI\n\n`sandbar` creates and manages sandboxes on any Sandbar provider. It is built for agents: it never prompts, every command has a stable `--json` form, and exit codes tell you what to do next.\n\n## Check the setup first\n\n```sh\nsandbar doctor --json      # config, credentials, provider connection; creates nothing\nsandbar providers --json   # which adapters are installed and which credentials are missing\n```\n\n- If `sandbar` is not on PATH, stop and tell the user; do not install anything yourself.\n- The provider comes from `--profile`, `SANDBAR_PROFILE`, `--provider`, `SANDBAR_PROVIDER`, then `default` in `~/.config/sandbar/sandbar.json`. Do not edit that file or credentials unless the user asks.\n- A missing adapter (exit 4, `ADAPTER_NOT_INSTALLED`), an installed adapter that fails to load (exit 4, `ADAPTER_LOAD_FAILED`) or a missing credential (exit 2) is the user's to fix. Report the `hint` from the error.\n\n**Sandboxes cost money.** Create only what the task needs and destroy it when done.\n\n## Always use JSON\n\nPass `--json` (or set `SANDBAR_JSON=1`). stdout then holds exactly one document:\n\n```json\n{\"ok\": true, \"data\": {...}}\n{\"ok\": false, \"error\": {\"code\": \"...\", \"message\": \"...\", \"retryable\": false, \"outcome\": \"rejected\", \"hint\": \"...\", \"known\": {...}}}\n```\n\nDiagnostics go to stderr. Read `error.hint` before deciding what to do.\n\n## One-shot work: `run`\n\n`run` creates a sandbox, runs one command and always destroys it. Prefer it whenever you do not need the sandbox afterwards.\n\n```sh\nsandbar run --json -- python3 -c 'print(2 + 2)'\nsandbar run --json --prepared base --timeout 5m -- sh -c 'pip install -q requests && python3 app.py'\n```\n\nPass the command after `--` as separate arguments. Its data is `{exitCode, stdout, stderr, truncated, sandbox}`, where `sandbox` names the sandbox it created and destroyed.\n\n## Longer work: create, use, remove\n\n```sh\nsandbar create --json --name job-1 --prepared base   # prints the name; reuse it everywhere\nsandbar cp ./app.py job-1:/home/user/app.py\nsandbar exec --json job-1 --cwd /home/user -- python3 app.py\nsandbar sh --json job-1 'cd /home/user && ls -la | head'\nsandbar cat job-1:/home/user/out.txt\nsandbar rm --json job-1\n```\n\n- Give sandboxes a `--name` so you can find them again; names are lowercase letters, digits and dashes. `--if-not-exists` reuses a live sandbox with that name instead of failing.\n- `exec` takes an argv after `--`; no shell runs. Use `sh` only when you need pipes, redirects or `&&`. For a script that starts with `-`, put it after `--`: `sandbar sh job-1 -- '-n ...'`.\n- `--env K=V` (repeatable), `--cwd`, `--stdin` or `--stdin-file <path>`, `--timeout 30s|5m|1h`, `--max-output 1m`.\n- `cp` copies one file; one side is `<sandbox>:/absolute/path`. `--no-clobber` refuses to overwrite.\n- `--image <oci-ref>` boots an OCI image where the provider supports it; `--prepared <id>` uses a provider template or snapshot. On providers that need a build first (E2B, Daytona), `--image` fails with exit 4 and `UNSUPPORTED` before creating anything until `sandbar image build <oci-ref>` has run once for that profile; later creates reuse the build. Build once rather than passing `--build` in a loop: a build is slow, may cost money and leaves a provider-side resource. `sandbar image ls` shows the builds; `sandbar image forget <name>` drops a record and lists what the provider still holds.\n- `sandbar ls --json` lists known sandboxes with their live state (`running`, `gone`, `unreachable`, ...). `sandbar inspect --json <name>` shows state, expiry and the saved reference.\n\nAlways `rm` what you created before finishing, even after failures. `rm` only destroys sandboxes this CLI created; never pass `--force` or `rm --all` unless the user asked.\n\n## Exit codes\n\n`exec`, `sh` and `run` exit with the **remote command's** exit code. Their own failures always exit **125**, with the error in the JSON document. A command that ran but reported no exit status is 125 with `OUTCOME_UNKNOWN`; its output is in `error.known.exec`. It is never success.\n\nOther commands:\n\n| Code | Meaning                                                           | What to do                                           |\n| ---- | ----------------------------------------------------------------- | ---------------------------------------------------- |\n| 0    | success                                                           |                                                      |\n| 1    | other failure, including a name already taken                     | read the message                                     |\n| 2    | usage or local error                                              | fix the command; `sandbar <command> --help`          |\n| 3    | not found                                                         | `sandbar ls`                                         |\n| 4    | unsupported, adapter or tool not installed, limit reached         | tell the user; do not work around it                 |\n| 5    | authentication, permission, or unreadable password-manager secret | tell the user                                        |\n| 6    | **outcome unknown**: the effect may have happened                 | **do not retry**; run `sandbar ls` / `inspect` first |\n| 7    | retryable (rate limit, capacity, unavailable) before any effect   | wait, then retry once or twice                       |\n| 8    | partial: some steps happened                                      | read `error.known` and `error.details`               |\n\n## When things go wrong\n\n- **Never repeat a create after exit 6 or `outcome: \"unknown\"`.** The store keeps the name in status `unknown`; check `sandbar ls --json`. `sandbar rm <name>` first asks the provider how that create ended (never resending it) and destroys the sandbox if one exists. If it still exits 4 because the outcome is unknown, and the user agrees it is gone, `sandbar rm --force <name>` drops the record.\n- **`run` exits 125 with `CLEANUP_FAILED`**: the command result is in `error.known.exec`, but the sandbox is still running. Tell the user and run the `rm` from the hint.\n- **`rm` exits 8**: `error.details` lists what was `removed`, `skipped` and `failed`. Retry only the failed names once the cause is fixed.\n- **`STORE_WRITE_FAILED`**: the sandbox exists but was not recorded. The reference is in `error.known.reference`; save it to a file and destroy with `sandbar rm @file.json`.\n- Interrupting `run` (Ctrl-C, SIGTERM) still destroys its sandbox and exits 130 (143 for SIGTERM) with `INTERRUPTED`. A second signal exits immediately and may leave it running.\n\n## Discover more\n\n`sandbar schema` prints every command, flag and exit code as JSON. `sandbar <command> --help` shows usage and examples.\n";
 
 // src/skill.ts
 var skillName = "sandbar-cli";
@@ -1741,6 +2043,21 @@ async function complete(words, commands, globals, session) {
       candidates: [{ value: "install", description: "Install the skill for your agents" }],
       directive: 0
     };
+  if (command.name === "image") {
+    if (positionals.length === 0)
+      return { candidates: imageActions.map((action) => ({ value: action })), directive: 0 };
+    if (positionals.length === 1 && (positionals[0] === "inspect" || positionals[0] === "forget")) {
+      const entries = await listAll(await session.store(), "image");
+      return {
+        candidates: entries.map(({ record }) => ({
+          value: record.name,
+          description: `${record.source} on ${record.profile}`
+        })),
+        directive: 0
+      };
+    }
+    return none;
+  }
   if (command.name === "completion" && positionals.length === 0)
     return { candidates: shells.map((shell) => ({ value: shell })), directive: 0 };
   return none;
@@ -1899,7 +2216,7 @@ var createFlags = {
   label: { type: "string", multiple: true, value: "k=v", description: "Label to set (repeatable)" },
   build: {
     type: "boolean",
-    description: "Build --image first when the provider needs it (not available yet)"
+    description: "Build --image now if this provider needs a build and none is recorded"
   }
 };
 var execFlags = {
@@ -2021,6 +2338,28 @@ var commands = [
     ],
     run: runCommand
   },
+  {
+    name: "image",
+    summary: "Build OCI images for providers that need it, and list or forget the builds",
+    usage: "sandbar image build <oci-ref> [--name <name>] [--refresh] | ls | inspect <name> | forget <name>",
+    flags: {
+      name: {
+        type: "string",
+        value: "name",
+        description: "Record name for a build (default: from the reference, like python-3-12)"
+      },
+      refresh: { type: "boolean", description: "Build again even if this reference is recorded" }
+    },
+    passthrough: false,
+    remoteExit: false,
+    examples: [
+      "sandbar image build python:3.12 --provider e2b",
+      "sandbar create --image python:3.12 --provider e2b",
+      "sandbar image ls",
+      "sandbar image forget python-3-12"
+    ],
+    run: imageCommand
+  },
   {
     name: "cp",
     summary: "Copy one file to or from a sandbox",
@@ -2108,7 +2447,7 @@ var exitCodes = [
   { code: 3, meaning: "not found" },
   {
     code: 4,
-    meaning: "unsupported by this provider or profile, adapter or password-manager CLI not installed, or store limit reached"
+    meaning: "unsupported by this provider or profile, adapter missing or broken, password-manager CLI not installed, or store limit reached"
   },
   {
     code: 5,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandbar-sdk/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "Agent-first command line for creating and managing Sandbar sandboxes.",
@@ -20,11 +20,17 @@
     "build": "rm -rf dist && bun build src/main.ts --target node --format esm --outdir dist --external sandbar-sdk --external @sandbar-sdk/adapter --external zod"
   },
   "dependencies": {
-    "@sandbar-sdk/adapter": "0.3.0",
-    "sandbar-sdk": "0.3.0",
+    "@sandbar-sdk/adapter": "0.5.0",
+    "sandbar-sdk": "0.5.0",
     "zod": "4.6.5"
   },
   "devDependencies": {
+    "@sandbar-sdk/boat": "0.5.0",
+    "@sandbar-sdk/boxd": "0.5.0",
+    "@sandbar-sdk/daytona": "0.5.0",
+    "@sandbar-sdk/e2b": "0.5.0",
+    "@sandbar-sdk/modal": "0.0.0",
+    "@sandbar-sdk/vercel": "0.5.0",
     "@sandbar/provider-fake": "0.0.0"
   },
   "license": "Apache-2.0",