@sandbar-sdk/cli 0.4.0 → 0.6.0

package/README.md

@@ -30,7 +30,7 @@ The adapter package must be installed where the CLI can find it: in `~/.config/s
 | `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 |
+| `image ls [--remote]`, `image inspect <name>`, `image rm <name> [--force]`, `image forget <name>` | List, show, delete or drop image records; `ls --remote` lists the provider's images, `rm` deletes a built image on the provider (only builds this CLI created unless `--force`), `forget` only drops the record |
 | `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 |
@@ -69,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`, 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.
+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`, `image rm` and `image forget`. Sandbox names come from the local store, so pressing tab never calls a provider.
 
 ## Agent skill
 
@@ -93,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
@@ -127,7 +127,7 @@ If the tool is not installed the command exits 4 (`SECRET_TOOL_MISSING`); if it
   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.
+`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 rm <name>` deletes a built image on the provider through `images.delete` and then drops the record; it works where the provider supports image deletion (E2B and Daytona) and exits 4 with `UNSUPPORTED` elsewhere. Without `--force` it only deletes builds this CLI verifiably created, so a build recovered from an older record or of unknown ownership needs `--force`. It refuses, with no effect, a record without a confirmed build, a record that shares the same prepared image, and an image the provider reports as public, shared or still in use. An image that is already gone counts as deleted. If the delete's outcome is unknown, `rm` exits 6, keeps the record in a `deleting` state with its recovery reference, and the next `image rm` asks the provider how the original request ended instead of sending it again. If the provider gives no operation to check, the record stays built and `rm` says so; check the provider before running it again, which sends a new delete. If that check itself fails (for example the profile now reaches another account), the record stays `deleting` with its recovery reference, so a later `image rm` from the original account can still check it. `image forget` removes the record without deleting anything and prints the resources the provider still holds. `image ls --remote` lists the images the provider reports for the profile (up to 1,000), marks the ones with a local record, and says how complete the provider's listing is; a listed image is not proof that you own it. 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
 
@@ -135,7 +135,7 @@ Sandbox references are kept as one JSON file per sandbox in `~/.config/sandbar/s
 
 ## Not yet
 
-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.
+Planned for later steps: `--lifetime`/`--idle`/`--port` create flags, recursive `cp`, detached processes and logs, preview URLs, suspend/resume/renew, `gc`, snapshots and volumes, `sandbar adapter add`, an S3-compatible store, KeePassXC and system-keyring references, and MCP mode.
 
 ## Development
 

package/dist/main.js

@@ -5,7 +5,7 @@ import { parseArgs } from "node:util";
 // package.json
 var package_default = {
   name: "@sandbar-sdk/cli",
-  version: "0.4.0",
+  version: "0.6.0",
   private: false,
   type: "module",
   description: "Agent-first command line for creating and managing Sandbar sandboxes.",
@@ -30,6 +30,7 @@ var package_default = {
     zod: "4.6.5"
   },
   devDependencies: {
+    "@sandbar-sdk/boat": "workspace:*",
     "@sandbar-sdk/boxd": "workspace:*",
     "@sandbar-sdk/daytona": "workspace:*",
     "@sandbar-sdk/e2b": "workspace:*",
@@ -59,9 +60,10 @@ import {
   Image as Image2,
   NonzeroExitError,
   ResourceReference as ResourceReference2,
-  SandbarError as SandbarError3
+  SandbarError as SandbarError3,
+  assertResourceScope
 } from "sandbar-sdk";
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // src/config.ts
 import { readFile } from "node:fs/promises";
@@ -316,6 +318,7 @@ function resolveEnvReferences(value, env, where) {
 
 // src/images.ts
 import { randomBytes as randomBytes2 } from "node:crypto";
+import { z as z3 } from "zod";
 import {
   Image,
   SandbarError as SandbarError2
@@ -339,6 +342,7 @@ var SandboxRecord = z2.strictObject({
   labels: z2.record(z2.string(), z2.string()),
   image: z2.string().optional(),
   reference: ResourceReference.extend({ kind: z2.literal("sandbox") }).nullable(),
+  adopted: z2.literal(true).optional(),
   recovery: z2.custom((value) => z2.record(z2.string(), z2.unknown()).safeParse(value).success).optional()
 });
 var RetainedResource = z2.strictObject({
@@ -351,7 +355,7 @@ var ImageRecord = z2.strictObject({
   format: z2.literal(1),
   kind: z2.literal("image"),
   name: RecordName,
-  status: z2.enum(["building", "built", "unknown"]),
+  status: z2.enum(["building", "built", "unknown", "deleting"]),
   profile: z2.string().min(1),
   provider: z2.string().min(1),
   createdAt: z2.iso.datetime({ offset: true }),
@@ -363,6 +367,7 @@ var ImageRecord = z2.strictObject({
     scope: ResourceReference.shape.scope
   }).nullable(),
   retainedResources: z2.array(RetainedResource),
+  reference: ResourceReference.extend({ kind: z2.literal("image") }).optional(),
   recovery: z2.custom((value) => z2.record(z2.string(), z2.unknown()).safeParse(value).success).optional()
 });
 var schemas = { sandbox: SandboxRecord, image: ImageRecord };
@@ -526,16 +531,21 @@ function generatedName() {
 }
 
 // src/images.ts
-var BuildResult = ImageRecord.pick({ prepared: true, retainedResources: true }).extend({
+var BuildResult = ImageRecord.pick({
+  prepared: true,
+  retainedResources: true,
+  reference: true
+}).extend({
   prepared: ImageRecord.shape.prepared.unwrap()
 });
+var DeleteResult = z3.looseObject({ deleted: z3.literal(true) });
 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);
+  return entries.find(({ record }) => record.profile === profile && record.source === source && record.prepared && record.status !== "deleting");
 }
 function mergeRetained(previous, next) {
   const seen = new Set(previous.map((item) => `${item.kind}/${item.id}`));
@@ -609,7 +619,8 @@ async function buildImage(session, client, profile, source, options) {
     status: "built",
     createdAt: new Date().toISOString(),
     prepared: result.prepared,
-    retainedResources: mergeRetained(claimed.record.retainedResources, result.retainedResources)
+    retainedResources: mergeRetained(claimed.record.retainedResources, result.retainedResources),
+    reference: result.reference
   };
   try {
     const { version } = await store.update("image", record.name, record, claimed.version);
@@ -715,7 +726,12 @@ async function inspectImage(session, args) {
     `built     ${record.createdAt}`,
     ...record.retainedResources.length ? ["retained", ...retainedLines(record)] : []
   ];
-  session.ctx.out.success({ ...summary(record), preparedImage: record.prepared, recovery: record.recovery ?? null }, lines.join(`
+  session.ctx.out.success({
+    ...summary(record),
+    preparedImage: record.prepared,
+    reference: record.reference ?? null,
+    recovery: record.recovery ?? null
+  }, lines.join(`
 `));
   return 0;
 }
@@ -727,25 +743,171 @@ async function forgetImage(session, args) {
   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));
+    lines.push(`${record.provider} still holds these; forget never deletes them (\`sandbar image rm\` does, where the provider supports it):`, ...retainedLines(record));
   session.ctx.out.success({ name: record.name, result: "forgotten", retainedResources: record.retainedResources }, lines.join(`
 `));
   return 0;
 }
-var imageActions = ["build", "ls", "inspect", "forget"];
+function recordReference(record) {
+  if (record.reference)
+    return record.reference;
+  if (!record.prepared)
+    return null;
+  return {
+    version: 1,
+    kind: "image",
+    provider: record.prepared.provider,
+    scope: structuredClone(record.prepared.scope),
+    nativeId: record.prepared.value,
+    ownership: "unknown"
+  };
+}
+async function forgetDeleted(store, entry) {
+  const current = await store.get("image", entry.record.name);
+  if (current?.version === entry.version)
+    await store.remove("image", entry.record.name, entry.version);
+}
+function deletedOutput(session, record, result) {
+  const prepared = record.prepared?.value ?? null;
+  const others = record.retainedResources.filter((item) => item.id !== prepared);
+  const lines = [result === "gone" ? `${record.name} was already gone` : `deleted ${record.name}`];
+  if (others.length)
+    lines.push(`${record.provider} still holds these from earlier builds:`, ...retainedLines({ ...record, retainedResources: others }));
+  session.ctx.out.success({ name: record.name, result, prepared, retainedResources: others }, lines.join(`
+`));
+  return 0;
+}
+async function rmImage(session, args, force) {
+  if (args.length !== 1)
+    throw usage("Expected exactly one image name");
+  const store = await session.store();
+  const entry = await recoverBuild(session, store, await findImage(store, args[0]));
+  const { record } = entry;
+  const client = await session.connect(await session.profileNamed(record.profile));
+  if (record.status === "deleting") {
+    if (record.recovery?.kind !== "image_delete") {
+      const { recovery: _recovery, ...rest } = record;
+      await store.update("image", record.name, { ...rest, status: "built" }, entry.version);
+      throw new CliError("OUTCOME_UNKNOWN", `${record.name} has no saved delete to check`, `the store keeps ${record.name} as built; check the provider (\`sandbar image ls --remote\`) before running \`sandbar image rm ${record.name}\` again, which sends a new delete`, { image: record.name });
+    }
+    let value;
+    try {
+      value = await (await client.recover(record.recovery)).observe();
+    } catch (cause) {
+      if (!(cause instanceof SandbarError2))
+        throw cause;
+      if (cause.effect === "none")
+        throw new CliError(cause.code, cause.message, `the store keeps ${record.name} deleting; run \`sandbar image rm ${record.name}\` again with profile ${record.profile} connected to the account the delete was sent from`, { image: record.name, recovery: record.recovery });
+    }
+    if (!DeleteResult.safeParse(value).success)
+      throw new CliError("OUTCOME_UNKNOWN", `The delete of ${record.name} is still unconfirmed`, `the store keeps ${record.name}; run \`sandbar image rm ${record.name}\` again later`, { image: record.name, recovery: record.recovery });
+    await forgetDeleted(store, entry);
+    return deletedOutput(session, record, "deleted");
+  }
+  const reference = recordReference(record);
+  if (record.status !== "built" || !reference)
+    throw new CliError("CONFLICT", `${record.name} has no confirmed build to delete`, "`sandbar image inspect` checks an uncertain build; `sandbar image forget` drops the record");
+  if (reference.ownership !== "verified-created" && !force)
+    throw new CliError("FORBIDDEN", `${record.name} was not created by this CLI (ownership ${reference.ownership})`, "pass --force to delete it anyway", { image: record.name });
+  const capabilities = await client.capabilities();
+  if (capabilities.imageManagement.delete.status !== "supported")
+    throw new CliError("UNSUPPORTED", `${record.provider} cannot delete images through Sandbar`, "`sandbar image forget` drops the record; delete the image with the provider's own tools");
+  const shared = (await listAll(store, "image")).find((other) => other.record.name !== record.name && other.record.profile === record.profile && other.record.prepared?.value === reference.nativeId);
+  if (shared)
+    throw new CliError("CONFLICT", `${record.name} and ${shared.record.name} record the same provider image`, "forget one record first, so the other is not left pointing at a deleted image");
+  try {
+    await client.images.delete(reference, { signal: session.ctx.signal });
+  } catch (cause) {
+    const report = describeError(cause);
+    if (report.outcome === "rejected" && report.code === "NOT_FOUND") {
+      await forgetDeleted(store, entry);
+      return deletedOutput(session, record, "gone");
+    }
+    if (report.outcome === "rejected")
+      throw cause;
+    const recovery = report.known?.recovery;
+    if (!recovery)
+      throw new CliError("OUTCOME_UNKNOWN", report.message, `the store keeps ${record.name} as built and there is no saved delete to check; check the provider (\`sandbar image ls --remote\`) before running \`sandbar image rm ${record.name}\` again, which sends a new delete`, { image: record.name });
+    let kept = `the store keeps ${record.name}; run \`sandbar image rm ${record.name}\` again to check`;
+    try {
+      await store.update("image", record.name, { ...record, status: "deleting", recovery }, entry.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: record.name,
+      recovery
+    });
+  }
+  await forgetDeleted(store, entry);
+  return deletedOutput(session, record, "deleted");
+}
+function remoteRow(info, records) {
+  const recorded = records.find(({ record }) => record.prepared?.value === info.reference.nativeId)?.record.name;
+  return {
+    id: info.reference.nativeId,
+    state: info.state,
+    visibility: info.visibility,
+    source: info.source?.value ?? null,
+    createdAt: info.createdAt,
+    record: recorded ?? null,
+    reference: info.reference
+  };
+}
+async function lsRemote(session) {
+  const profile = await session.profile();
+  const client = await session.connect(profile);
+  const capabilities = await client.capabilities();
+  if (capabilities.imageManagement.list.status !== "supported")
+    throw new CliError("UNSUPPORTED", `${profile.provider} cannot list images through Sandbar`, "`sandbar image ls` shows the builds this store recorded");
+  const records = (await listAll(await session.store(), "image")).filter(({ record }) => record.profile === profile.name);
+  const rows = [];
+  let cursor;
+  let coverage = capabilities.imageManagement.list.value.coverage;
+  for (let page = 0;page < 10; page++) {
+    const result = await client.images.list({ limit: 100, cursor });
+    coverage = result.coverage;
+    rows.push(...result.items.map((info) => remoteRow(info, records)));
+    cursor = result.nextCursor;
+    if (!cursor)
+      break;
+  }
+  if (cursor)
+    session.ctx.out.note(`showing the first ${rows.length} images; more exist`);
+  const lines = rows.map((row) => [
+    row.id.padEnd(28),
+    row.state.padEnd(9),
+    row.visibility.padEnd(10),
+    (row.record ?? "-").padEnd(20),
+    row.source ?? "-"
+  ].join(" "));
+  session.ctx.out.success({ profile: profile.name, coverage, images: rows, truncated: !!cursor }, rows.length ? [
+    `${"ID".padEnd(28)} ${"STATE".padEnd(9)} ${"VISIBILITY".padEnd(10)} ${"RECORD".padEnd(20)} SOURCE`,
+    ...lines
+  ].join(`
+`) : `no images on ${profile.provider} for profile ${profile.name}`);
+  return 0;
+}
+var imageActions = ["build", "ls", "inspect", "rm", "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`");
+  if (flags.bool("remote") && action !== "ls")
+    throw usage("--remote only applies to `sandbar image ls`");
+  if (flags.bool("force") && action !== "rm")
+    throw usage("--force only applies to `sandbar image rm`");
   switch (action) {
     case "build":
       return buildCommand(session, flags, args);
     case "ls":
       if (args.length)
         throw usage("image ls takes no arguments");
-      return lsImages(session);
+      return flags.bool("remote") ? lsRemote(session) : lsImages(session);
     case "inspect":
       return inspectImage(session, args);
+    case "rm":
+      return rmImage(session, args, flags.bool("force"));
     case "forget":
       return forgetImage(session, args);
     default:
@@ -761,7 +923,7 @@ import {
   bindAdapter
 } from "@sandbar-sdk/adapter";
 import { Sandbar } from "sandbar-sdk";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var providers = [
   {
     id: "daytona",
@@ -790,6 +952,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",
@@ -857,7 +1029,7 @@ function fromProfile(name, profile, loaded, env) {
     }),
     ...Object.entries(profile.credentials ?? {}).map(([key, value]) => [
       key,
-      z3.string().parse(resolveEnvReferences(value, env, `${where}.credentials.${key}`))
+      z4.string().parse(resolveEnvReferences(value, env, `${where}.credentials.${key}`))
     ])
   ]);
   const config = Object.fromEntries([
@@ -886,9 +1058,9 @@ function fromProfile(name, profile, loaded, env) {
     credentials
   };
 }
-var PackageManifest = z3.object({
-  main: z3.string().optional(),
-  exports: z3.json().optional()
+var PackageManifest = z4.object({
+  main: z4.string().optional(),
+  exports: z4.json().optional()
 });
 async function exists(path) {
   try {
@@ -900,10 +1072,10 @@ async function exists(path) {
 }
 var importConditions = new Set(["import", "node", "default"]);
 function exportTarget(value) {
-  const plain = z3.string().safeParse(value);
+  const plain = z4.string().safeParse(value);
   if (plain.success)
     return plain.data;
-  const list = z3.array(z3.json()).safeParse(value);
+  const list = z4.array(z4.json()).safeParse(value);
   if (list.success) {
     for (const item of list.data) {
       const target = exportTarget(item);
@@ -912,7 +1084,7 @@ function exportTarget(value) {
     }
     return null;
   }
-  const conditions = z3.record(z3.string(), z3.json()).safeParse(value);
+  const conditions = z4.record(z4.string(), z4.json()).safeParse(value);
   if (!conditions.success)
     return null;
   for (const [condition, nested] of Object.entries(conditions.data)) {
@@ -928,7 +1100,7 @@ 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 subpaths = z4.record(z4.string(), z4.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";
 }
@@ -969,7 +1141,7 @@ async function resolveAdapterModule(profile, cwd, env) {
 function isAdapter(value) {
   return value instanceof Object && "name" in value && "connect" in value && "config" in value;
 }
-var AdapterExport = z3.custom(isAdapter);
+var AdapterExport = z4.custom(isAdapter);
 async function adapterMissing(target, spec, message) {
   if (target.startsWith("file:"))
     return !await exists(fileURLToPath(target));
@@ -977,7 +1149,7 @@ async function adapterMissing(target, spec, message) {
 }
 async function loadAdapter(profile, cwd, env, secrets) {
   const target = await resolveAdapterModule(profile, cwd, env);
-  const schema = z3.object({ [profile.export]: AdapterExport });
+  const schema = z4.object({ [profile.export]: AdapterExport });
   let parsed;
   try {
     parsed = schema.safeParse(await import(target));
@@ -997,7 +1169,7 @@ 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 = z3.record(z3.string(), z3.string()).parse(await secrets.resolve(profile.credentials, `${where}.credentials`));
+  const credentials = z4.record(z4.string(), z4.string()).parse(await secrets.resolve(profile.credentials, `${where}.credentials`));
   return bindAdapter(exported, config, credentials);
 }
 async function connect(profile, cwd, env, secrets) {
@@ -1053,16 +1225,16 @@ class Flags {
     this.rest = rest;
   }
   string(name) {
-    return z4.string().optional().parse(this.values[name]);
+    return z5.string().optional().parse(this.values[name]);
   }
   strings(name) {
-    return z4.array(z4.string()).optional().parse(this.values[name]) ?? [];
+    return z5.array(z5.string()).optional().parse(this.values[name]) ?? [];
   }
   bool(name) {
-    return z4.boolean().optional().parse(this.values[name]) ?? false;
+    return z5.boolean().optional().parse(this.values[name]) ?? false;
   }
 }
-function createRequest(flags) {
+function createRequest(flags, env = {}) {
   if (flags.string("image") && flags.string("prepared"))
     throw usage("Pass either --image or --prepared, not both");
   if (flags.bool("build") && !flags.string("image"))
@@ -1074,14 +1246,89 @@ function createRequest(flags) {
     image: flags.string("image"),
     prepared: flags.string("prepared"),
     network: flags.string("network"),
-    labels: parsePairs(flags.strings("label"), "label")
+    labels: parsePairs(flags.strings("label"), "label"),
+    env
   };
 }
+var EnvName = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var escapes = new Map([
+  ["n", `
+`],
+  ['"', '"'],
+  ["\\", "\\"]
+]);
+function envFileValue(text) {
+  const value = text.trimStart();
+  const quote = value[0];
+  if (quote !== '"' && quote !== "'")
+    return { value: text.replace(/\s#.*$/s, "").trim() };
+  let parsed = "";
+  let end = -1;
+  for (let at = 1;at < value.length; at++) {
+    const char = value[at];
+    if (char === quote) {
+      end = at;
+      break;
+    }
+    if (quote === '"' && char === "\\" && at + 1 < value.length) {
+      const next = value[++at];
+      parsed += escapes.get(next) ?? `\\${next}`;
+    } else
+      parsed += char;
+  }
+  if (end < 0)
+    return { error: "has an unterminated quoted value; multi-line values are not supported" };
+  if (!/^\s*(#.*)?$/s.test(value.slice(end + 1)))
+    return { error: "has text after the closing quote" };
+  return { value: parsed };
+}
+async function envFlags(session, flags) {
+  const env = {};
+  for (const file of flags.strings("env-file")) {
+    const path = resolve3(session.ctx.cwd, file);
+    let text;
+    try {
+      text = await readFile4(path, "utf8");
+    } catch {
+      throw usage(`--env-file ${file} could not be read`);
+    }
+    for (const [index, raw] of text.split(/\r?\n/).entries()) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#"))
+        continue;
+      const assignment = line.startsWith("export ") ? line.slice(7).trimStart() : line;
+      const split = assignment.indexOf("=");
+      const name = split > 0 ? assignment.slice(0, split).trim() : "";
+      if (!EnvName.test(name))
+        throw usage(`--env-file ${file}:${index + 1} must be NAME=VALUE with a valid NAME`);
+      const parsed = envFileValue(assignment.slice(split + 1));
+      if ("error" in parsed)
+        throw usage(`--env-file ${file}:${index + 1} ${parsed.error}`);
+      env[name] = parsed.value;
+    }
+  }
+  for (const entry of flags.strings("env")) {
+    const split = entry.indexOf("=");
+    const name = split < 0 ? entry : entry.slice(0, split);
+    if (!EnvName.test(name))
+      throw usage("--env expects NAME=VALUE or NAME, with NAME like [A-Za-z_][A-Za-z0-9_]*");
+    if (split >= 0)
+      env[name] = entry.slice(split + 1);
+    else {
+      const inherited = session.ctx.env[name];
+      if (inherited === undefined)
+        throw usage(`--env ${name} is not set in this environment`);
+      env[name] = inherited;
+    }
+  }
+  return env;
+}
 function createInput(request) {
   return {
     environment: request.prepared ? Image2.prepared(request.prepared) : undefined,
     network: request.network,
-    labels: Object.keys(request.labels).length ? request.labels : undefined
+    labels: Object.keys(request.labels).length ? request.labels : undefined,
+    env: Object.keys(request.env).length ? request.env : undefined
   };
 }
 async function claimName(store, record, requested, ifNotExists = false) {
@@ -1192,7 +1439,8 @@ function sandboxSummary(record) {
     status: record.status,
     createdAt: record.createdAt,
     labels: record.labels,
-    image: record.image ?? null
+    image: record.image ?? null,
+    adopted: record.adopted ?? false
   };
 }
 async function findTarget(session, target) {
@@ -1224,13 +1472,15 @@ async function findTarget(session, target) {
     if (entry)
       return entry;
   }
-  const byId = (await listAll(store, "sandbox")).find((entry) => entry.record.reference?.nativeId === target);
-  if (byId)
-    return byId;
+  const byId = (await listAll(store, "sandbox")).filter((entry) => entry.record.reference?.nativeId === target);
+  if (byId.length > 1)
+    throw new CliError("CONFLICT", `${target} names more than one stored sandbox: ${byId.map((entry) => entry.record.name).join(", ")}`, "use the store name instead of the id");
+  if (byId[0])
+    return byId[0];
   throw new CliError("NOT_FOUND", `No sandbox named ${target} in the store`, "list known sandboxes with `sandbar ls`");
 }
 async function createCommand(session, flags) {
-  const created = await createSandbox(session, createRequest(flags));
+  const created = await createSandbox(session, createRequest(flags, await envFlags(session, flags)));
   if (created.unrecorded)
     throw unrecordedError(created);
   session.ctx.out.success({
@@ -1254,7 +1504,108 @@ async function stateOf(session, record, client) {
     return "unreachable";
   }
 }
+var REMOTE_PAGES = 20;
+async function remoteSandboxes(client, until) {
+  const items = [];
+  let cursor;
+  let coverage = "provider-scope";
+  for (let page = 0;page < REMOTE_PAGES; page++) {
+    const result = await client.sandboxes.list({ cursor, limit: 100 });
+    coverage = result.coverage;
+    items.push(...result.items);
+    cursor = result.nextCursor;
+    if (!cursor || until && result.items.some(until))
+      return { items, coverage, complete: true };
+  }
+  return { items, coverage, complete: false };
+}
+var coverageNote = {
+  "provider-scope": "every sandbox this profile's account and scope can see",
+  "sandbar-managed": "only sandboxes created through Sandbar in this profile's scope"
+};
+function renderTable(rows) {
+  const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+  return rows.map((row) => row.map((cell, column) => cell.padEnd(widths[column])).join("  ").trimEnd()).join(`
+`);
+}
+async function remoteLs(session) {
+  const { out } = session.ctx;
+  const profile = await session.profile();
+  const entries = await listAll(await session.store(), "sandbox", (warning) => out.note(warning));
+  const client = await session.connect(profile);
+  const listing = await remoteSandboxes(client);
+  const nameOf = (item) => entries.find(({ record }) => storesSandbox(record, profile, client, item))?.record.name ?? null;
+  const rows = listing.items.map((item) => ({
+    id: item.id,
+    state: item.state,
+    name: nameOf(item),
+    reopenable: item.reference !== null,
+    ownership: item.reference?.ownership ?? null,
+    reference: item.reference
+  }));
+  out.note(`${profile.provider} lists ${coverageNote[listing.coverage]}`);
+  if (!listing.complete)
+    out.note(`warning: showing the first ${rows.length} sandboxes; the provider has more`);
+  out.success({
+    provider: profile.provider,
+    profile: profile.name,
+    coverage: listing.coverage,
+    complete: listing.complete,
+    sandboxes: rows
+  }, rows.length ? renderTable([
+    ["ID", "STATE", "NAME", "OWNERSHIP"],
+    ...rows.map((row) => [
+      row.id,
+      row.state,
+      row.name ?? "-",
+      row.ownership ?? "not reopenable"
+    ])
+  ]) : "");
+  return 0;
+}
+async function adoptCommand(session, flags) {
+  const id = onePositional(flags, "sandbox id");
+  const requested = flags.string("name");
+  const store = await session.store();
+  const profile = await session.profile();
+  const client = await session.connect(profile);
+  const listing = await remoteSandboxes(client, (item) => item.id === id);
+  const listed = listing.items.find((item) => item.id === id);
+  const known = listed && (await listAll(store, "sandbox")).find(({ record: record2 }) => storesSandbox(record2, profile, client, listed));
+  if (known)
+    throw new CliError("CONFLICT", `${id} is already in the store as ${known.record.name}`, `use \`sandbar inspect ${known.record.name}\``);
+  if (!listed)
+    throw new CliError("NOT_FOUND", `${profile.provider} does not list a sandbox ${id} for profile ${profile.name}`, listing.complete ? "list what it does show with `sandbar ls --remote`" : "the listing was cut short; check the provider's own tools");
+  if (!listed.reference)
+    throw new CliError("UNSUPPORTED", `${profile.provider} lists ${id} without a reopenable reference`, "this provider cannot verify that sandbox's identity, so the CLI cannot reach it");
+  const box = await client.sandboxes.get(listed.reference, { signal: session.ctx.signal });
+  const record = {
+    format: 1,
+    kind: "sandbox",
+    status: "created",
+    profile: profile.name,
+    provider: profile.provider,
+    createdAt: new Date().toISOString(),
+    labels: {},
+    reference: box.reference ?? listed.reference,
+    adopted: true
+  };
+  let claimed;
+  try {
+    claimed = await claimName(store, record, requested);
+  } catch (cause) {
+    if (cause instanceof CliError && cause.code === "CONFLICT")
+      throw new CliError("CONFLICT", cause.message, "choose another --name");
+    throw cause;
+  }
+  session.ctx.out.success({ ...sandboxSummary(claimed.record), id: box.id, reference: claimed.record.reference }, claimed.record.name);
+  return 0;
+}
 async function lsCommand(session, flags) {
+  if (flags.bool("remote") && flags.bool("offline"))
+    throw usage("Pass either --remote or --offline, not both");
+  if (flags.bool("remote"))
+    return remoteLs(session);
   const entries = await listAll(await session.store(), "sandbox", (warning) => session.ctx.out.note(warning));
   const offline = flags.bool("offline");
   const clients = new Map;
@@ -1314,10 +1665,30 @@ async function inspectCommand(session, flags) {
 function refusal(record) {
   if (!record.reference)
     return new CliError("UNSUPPORTED", `${record.name} has no reopenable reference (status ${record.status}); it cannot be destroyed from here`, "check the provider for it, then `sandbar rm --force` to drop the record", { sandbox: record.name });
+  if (record.adopted)
+    return new CliError("FORBIDDEN", `${record.name} was adopted from a provider listing, not created by this CLI`, "pass --force to destroy it anyway", { sandbox: record.name });
   if (record.reference.ownership !== "verified-created")
     return new CliError("FORBIDDEN", `${record.name} was not created by this CLI (ownership ${record.reference.ownership})`, "pass --force to destroy it anyway", { sandbox: record.name });
   return null;
 }
+function storesSandbox(record, profile, client, item) {
+  const stored = record.reference;
+  if (!stored || record.provider !== profile.provider || stored.nativeId !== item.id)
+    return false;
+  if (item.reference?.generation !== undefined && stored.generation !== undefined && stored.generation !== item.reference.generation)
+    return false;
+  try {
+    assertResourceScope(stored, {
+      provider: client.provider,
+      scope: item.reference?.scope ?? client.scope
+    });
+    return true;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "CONFLICT")
+      return false;
+    throw error;
+  }
+}
 function sameSandbox(a, b) {
   if (a.createdAt !== b.createdAt || a.provider !== b.provider || a.profile !== b.profile)
     return false;
@@ -1465,7 +1836,7 @@ async function execInput(session, flags, command) {
   const stdin = flags.bool("stdin") ? await session.ctx.readStdin() : stdinFile ? new Uint8Array(await readFile4(resolve3(session.ctx.cwd, stdinFile))) : undefined;
   const timeout = flags.string("timeout");
   const maxOutput = flags.string("max-output");
-  const env = parsePairs(flags.strings("env"), "env");
+  const env = await envFlags(session, flags);
   return {
     command,
     cwd: flags.string("cwd"),
@@ -1733,8 +2104,8 @@ async function providersCommand(session) {
 
 // src/secrets.ts
 import { execFile } from "node:child_process";
-import { z as z5 } from "zod";
-var BwsSecret = z5.object({ value: z5.string() });
+import { z as z6 } from "zod";
+var BwsSecret = z6.object({ value: z6.string() });
 var backends = [
   {
     name: "1Password",
@@ -1807,14 +2178,14 @@ class SecretReader {
     }
   }
   async resolve(value, where) {
-    const text = z5.string().safeParse(value);
+    const text = z6.string().safeParse(value);
     if (text.success) {
       const backend = backendFor(text.data);
       return backend ? this.read(backend, text.data, where) : value;
     }
     if (Array.isArray(value))
       return Promise.all(value.map((item, index) => this.resolve(item, `${where}[${index}]`)));
-    const record = z5.record(z5.string(), z5.json()).safeParse(value);
+    const record = z6.record(z6.string(), z6.json()).safeParse(value);
     if (record.success)
       return Object.fromEntries(await Promise.all(Object.entries(record.data).map(async ([key, item]) => [key, await this.resolve(item, `${where}.${key}`)])));
     return value;
@@ -1875,7 +2246,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`), 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";
+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), `--env-file <path>`, `--cwd`, `--stdin` or `--stdin-file <path>`, `--timeout 30s|5m|1h`, `--max-output 1m`.\n- On `create`, `--env K=V` and `--env-file <path>` set variables for every later `exec`/`sh` in that sandbox; a command's own `--env` wins. For a secret, pass `--env NAME` (no value) to copy it from your environment instead of typing it. Values are never stored or printed. Providers that cannot keep sandbox variables (boxd) fail with exit 4 and `UNSUPPORTED` before creating anything; pass `--env` on each `exec` there. On `run`, `--env` applies to its one command and works everywhere.\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 (`--remote` lists the provider's images instead); `sandbar image rm <name>` deletes a build on the provider and drops its record; `sandbar image forget <name>` only drops the record. Only `image rm` images you built for this task; it refuses builds this CLI did not verifiably create, and never pass `--force` unless the user asked. Exit 6 from `image rm` means the outcome is unknown: run `sandbar image rm <name>` again later to check, which never resends the delete.\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- `sandbar ls --remote --json` asks the provider instead of the store. `data.coverage` says whether it shows every sandbox in the account scope (`provider-scope`) or only Sandbar-created ones (`sandbar-managed`); `name` is the store name, or null for sandboxes this store does not know. `sandbar adopt <id> [--name <name>]` records a listed sandbox so `exec`, `cp` and `inspect` can reach it. Adopted sandboxes are not the CLI's own: `rm --all` skips them and `rm <name>` needs `--force`. Do not adopt or remove sandboxes the user did not ask about.\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";
@@ -1948,7 +2319,7 @@ ${marker}
 // src/completion.ts
 var NoSpace = 1;
 var Files = 2;
-var fileFlags = new Set(["config", "state-dir", "stdin-file"]);
+var fileFlags = new Set(["config", "state-dir", "stdin-file", "env-file"]);
 var sandboxArguments = new Map([
   ["inspect", 1],
   ["exec", 1],
@@ -2035,7 +2406,7 @@ async function complete(words, commands, globals, session) {
   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")) {
+    if (positionals.length === 1 && ["inspect", "forget", "rm"].includes(positionals[0])) {
       const entries = await listAll(await session.store(), "image");
       return {
         candidates: entries.map(({ record }) => ({
@@ -2203,6 +2574,18 @@ var createFlags = {
     description: "blocked or internet; default is the profile's policy"
   },
   label: { type: "string", multiple: true, value: "k=v", description: "Label to set (repeatable)" },
+  env: {
+    type: "string",
+    multiple: true,
+    value: "K=V",
+    description: "Environment variable for every command in the sandbox (repeatable; K alone copies it from here)"
+  },
+  "env-file": {
+    type: "string",
+    multiple: true,
+    value: "path",
+    description: "Read K=V lines into the sandbox environment (repeatable; --env wins)"
+  },
   build: {
     type: "boolean",
     description: "Build --image now if this provider needs a build and none is recorded"
@@ -2214,7 +2597,13 @@ var execFlags = {
     type: "string",
     multiple: true,
     value: "K=V",
-    description: "Environment variable (repeatable)"
+    description: "Environment variable for this command (repeatable; K alone copies it from here)"
+  },
+  "env-file": {
+    type: "string",
+    multiple: true,
+    value: "path",
+    description: "Read K=V lines into this command's environment (repeatable; --env wins)"
   },
   stdin: { type: "boolean", description: "Send this process's stdin to the command" },
   "stdin-file": {
@@ -2233,7 +2622,7 @@ var commands = [
   {
     name: "create",
     summary: "Create a sandbox and print its name",
-    usage: "sandbar create [--name <name>] [--image <oci-ref> | --prepared <id>] [--network <policy>]",
+    usage: "sandbar create [--name <name>] [--image <oci-ref> | --prepared <id>] [--network <policy>] [--env K=V]...",
     flags: {
       ...createFlags,
       "if-not-exists": {
@@ -2245,22 +2634,43 @@ var commands = [
     remoteExit: false,
     examples: [
       "sandbar create --name web --network internet",
-      "sandbar create --name job-42 --if-not-exists --json"
+      "sandbar create --name job-42 --if-not-exists --json",
+      "sandbar create --name ci --env-file .env --env API_TOKEN"
     ],
     run: createCommand
   },
   {
     name: "ls",
     summary: "List sandboxes in the store with their current state",
-    usage: "sandbar ls [--offline]",
+    usage: "sandbar ls [--offline | --remote]",
     flags: {
-      offline: { type: "boolean", description: "Show stored records without asking providers" }
+      offline: { type: "boolean", description: "Show stored records without asking providers" },
+      remote: {
+        type: "boolean",
+        description: "List the profile's sandboxes from the provider instead of the store"
+      }
     },
     passthrough: false,
     remoteExit: false,
-    examples: ["sandbar ls", "sandbar ls --json"],
+    examples: ["sandbar ls", "sandbar ls --json", "sandbar ls --remote --provider daytona"],
     run: lsCommand
   },
+  {
+    name: "adopt",
+    summary: "Add a sandbox from the provider's listing to the store so other commands reach it",
+    usage: "sandbar adopt <id> [--name <name>]",
+    flags: {
+      name: {
+        type: "string",
+        value: "name",
+        description: "Store name (default: generated, like sb-1a2b3)"
+      }
+    },
+    passthrough: false,
+    remoteExit: false,
+    examples: ["sandbar ls --remote", "sandbar adopt 4f1c2a --name worker"],
+    run: adoptCommand
+  },
   {
     name: "inspect",
     summary: "Show a sandbox's state, expiry and reference",
@@ -2329,15 +2739,23 @@ var commands = [
   },
   {
     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>",
+    summary: "Build OCI images for providers that need it, and list, delete or forget the builds",
+    usage: "sandbar image build <oci-ref> [--name <name>] [--refresh] | ls [--remote] | inspect <name> | rm <name> [--force] | 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" }
+      refresh: { type: "boolean", description: "Build again even if this reference is recorded" },
+      remote: {
+        type: "boolean",
+        description: "List the images on the provider for this profile, not the local records"
+      },
+      force: {
+        type: "boolean",
+        description: "Delete a recorded image this CLI did not verifiably create"
+      }
     },
     passthrough: false,
     remoteExit: false,
@@ -2345,6 +2763,8 @@ var commands = [
       "sandbar image build python:3.12 --provider e2b",
       "sandbar create --image python:3.12 --provider e2b",
       "sandbar image ls",
+      "sandbar image ls --remote --provider e2b",
+      "sandbar image rm python-3-12",
       "sandbar image forget python-3-12"
     ],
     run: imageCommand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandbar-sdk/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "description": "Agent-first command line for creating and managing Sandbar sandboxes.",
@@ -20,16 +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.4.0",
-    "sandbar-sdk": "0.4.0",
+    "@sandbar-sdk/adapter": "0.6.0",
+    "sandbar-sdk": "0.6.0",
     "zod": "4.6.5"
   },
   "devDependencies": {
-    "@sandbar-sdk/boxd": "0.4.0",
-    "@sandbar-sdk/daytona": "0.4.0",
-    "@sandbar-sdk/e2b": "0.4.0",
+    "@sandbar-sdk/boat": "0.6.0",
+    "@sandbar-sdk/boxd": "0.6.0",
+    "@sandbar-sdk/daytona": "0.6.0",
+    "@sandbar-sdk/e2b": "0.6.0",
     "@sandbar-sdk/modal": "0.0.0",
-    "@sandbar-sdk/vercel": "0.4.0",
+    "@sandbar-sdk/vercel": "0.6.0",
     "@sandbar/provider-fake": "0.0.0"
   },
   "license": "Apache-2.0",