@sanlabs/sanbox-cli 0.0.11 → 0.0.13

package/README.md

@@ -15,8 +15,14 @@ installed_cli_version="$(sanbox --version)"
 test "$installed_cli_version" = "$latest_cli_version"
 ```
 
-Always use the latest published CLI. CLI 0.0.11 adds OpenCode Computer templates and short-lived
-native SDK connections for HTTP, SSE streaming, and interactive steering.
+Always use the latest published CLI. CLI 0.0.13 allows service templates to start without an
+initial task, including OpenCode Computers that are ready for later SDK steering, and supports
+Custom OpenAI Proxy providers when creating templates, including Browser Use templates.
+CLI 0.0.12 adopted the Stop, Resume, and Delete lifecycle,
+separates run state from execution outcome, retains scrubbed deleted-run tombstones, and adds
+administrator-confirmed template deletion.
+CLI 0.0.11 added OpenCode Computer templates and short-lived native SDK connections for HTTP, SSE
+streaming, and interactive steering.
 CLI 0.0.10 added per-run Hermes email and Telegram channels, Supabase user authorization, and
 removed the retired run-chat commands.
 CLI 0.0.9 added user login for private SSH access to supported running sandboxes.
@@ -113,10 +119,20 @@ sanbox templates create \
 Omit both `--channel` flags for a WebUI-only computer. Channel credentials never belong to the
 template.
 
+Delete a template when it should no longer be available for new runs:
+
+```bash
+sanbox templates delete <template-id-or-slug> --force --json
+```
+
+Deletion preserves existing runs and retained sandboxes. It requires organization-admin access
+and `--force` so scripts cannot remove a template accidentally.
+
 ## Create A Browser Use Template
 
 Browser Use runs local headless Chromium inside the Firecracker sandbox. It requires OpenAI,
-Anthropic, Google Gemini, or Hetzner Inference and at least one explicit browser target:
+Anthropic, Google Gemini, Hetzner Inference, or a Custom OpenAI Proxy and at least one
+explicit browser target:
 
 ```bash
 sanbox templates create \
@@ -139,6 +155,8 @@ allowed downloads. Browser Use templates are one-shot agent executions.
 
 ## Run Idempotently
 
+Task templates require a positional task or `--task`. Service templates may omit it:
+
 ```bash
 sanbox run "Review this repo and write output/report.md" \
   --input src/ \
@@ -151,8 +169,18 @@ sanbox run "Review this repo and write output/report.md" \
   --input src/ \
   --wait \
   --json
+
+sanbox run \
+  --template "<service-template-id>" \
+  --external-run-id "<stable-service-id>" \
+  --json
 ```
 
+A taskless OpenCode Computer starts `opencode serve` without making an initial model call. A
+taskless Hermes service starts its gateways and waits for WebUI or configured channel messages.
+Supplying instructions starts the initial OpenCode task or seeds Hermes's persistent operating
+context, preserving the existing behavior.
+
 Repeat `--input` for files, directories, or globs. The CLI excludes common secrets and applies `.sanboxignore`. `--include` is a deprecated compatibility alias.
 
 For a Hermes template that allows `email`, optionally request an address from one of the AgentMail
@@ -200,7 +228,7 @@ callback lands on a Sanbox-hosted completion page, so a CLI demo does not need a
 Customer integrations may use `--return-url <https-url>` when its origin matches the return origin
 configured on the organization Supabase connection.
 
-Reuse the same external ID when retrying an ambiguous submission. To stream activity, replace `--wait --json` with `--jsonl`. Ctrl-C detaches without canceling unless `--cancel-on-interrupt` is supplied.
+Reuse the same external ID when retrying an ambiguous submission. To stream activity, replace `--wait --json` with `--jsonl`. Ctrl-C detaches without stopping unless `--stop-on-interrupt` is supplied.
 
 ## Inspect And Recover
 
@@ -243,20 +271,23 @@ working when the exact sandbox session stops, the link expires, or it is revoked
 when created and must be handled as a bearer secret. See
 [Live Filesystem Access](../docs/live-filesystem-access.md) for the HTTP contract and exclusions.
 
-## Resume Or Pause A Sandbox
+## Stop, Resume, Or Delete A Run
 
 ```bash
 sanbox runs get <run-id> --json
 sanbox runs resume <run-id> --wait --json
 sanbox runs share <run-id> --expires 1h --json
-sanbox runs pause <run-id> --wait --json
+sanbox runs stop <run-id> --wait --json
+sanbox runs delete <run-id> --yes --json
 ```
 
-Resume restores the latest writable Firecracker snapshot without starting the configured agent
-harness. It acquires an exclusive manual lease and leaves the sandbox running for live filesystem
-access until Pause creates the next snapshot generation. Before resuming, require
-`sandbox_state: "paused"` and a positive `snapshot_generation`. Do not submit agent work while that
-lease is active. Paused state has no retention TTL and remains available until explicitly deleted.
+Stop terminates compute and durably syncs the workspace. It does not retain RAM, process state, or
+network connections. Resume fresh-boots the pinned runtime artifact with the retained workspace; it
+does not silently replay a completed task. `state` is the single run phase; inspect
+`latest_execution.outcome` for the last bounded execution outcome and `workspace.saved_at` for disk
+persistence proof. Stopped runs have no automatic TTL. Delete permanently removes the workspace
+after archiving usage. The control plane retains a scrubbed run tombstone, but normal CLI run listings
+exclude deleted runs.
 
 ## SSH Into A Running Sandbox
 
@@ -274,8 +305,9 @@ authenticated WebSocket. The temporary key is deleted when the connection closes
 user token is not passed to the OpenSSH child process.
 
 OpenCode and Browser Use runs are one-shot agent executions. OpenCode Computer keeps its private
-server running after the initial task so it can accept later steering. A persisted task sandbox can
-still be resumed manually for inspection when a snapshot exists.
+server running so it can accept later steering; when an initial task is supplied, Sanbox submits it
+after the server becomes ready. A persisted task workspace can still be fresh-booted manually for
+inspection after the run stops.
 
 ## Connect The OpenCode SDK
 

package/dist/activity.js

@@ -35,6 +35,23 @@ export const formatActivityLine = (event, runCreatedAt) => {
     return `${elapsed(runCreatedAt, event.created_at).padStart(8)}  ${event.kind.padEnd(22)} ${bounded}`.trimEnd();
 };
 const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const legacyGuestEventKinds = new Set([
+    "log.stdout",
+    "log.stderr",
+    "runner.event_invalid",
+    "sandbox.stderr",
+    "anthropic.worker.stdout",
+    "anthropic.worker.stderr"
+]);
+const legacyEventSource = (event) => {
+    if (legacyGuestEventKinds.has(event.kind)) {
+        return { plane: "sandbox", trust: "legacy_guest_content" };
+    }
+    if (event.kind === "sandbox.status") {
+        return { plane: "unknown", trust: "legacy_mixed_origin" };
+    }
+    return { plane: "control_plane", trust: "control_plane" };
+};
 const safeEventData = (value) => {
     if (Array.isArray(value))
         return value.map(safeEventData);
@@ -61,7 +78,7 @@ export const activityEnvelope = (event) => {
         kind: event.kind,
         level: event.level,
         summary: event.message,
-        source: normalized ? event.payload.source : { plane: "control_plane", trust: "control_plane" },
+        source: normalized ? event.payload.source : legacyEventSource(event),
         sequence: normalized && typeof event.payload.sequence === "number" ? event.payload.sequence : null,
         correlation: normalized && isRecord(event.payload.correlation) ? event.payload.correlation : {},
         data: safeEventData(normalized ? event.payload.data : event.payload),

package/dist/api.js

@@ -174,6 +174,9 @@ export class SanboxClient {
     async validateTemplate(templateId) {
         return this.request(await this.orgPath(`/templates/${encodeURIComponent(templateId)}/validate`));
     }
+    async deleteTemplate(templateId) {
+        return this.request(await this.orgPath(`/templates/${encodeURIComponent(templateId)}`), { method: "DELETE" });
+    }
     async createTemplate(body) {
         return this.request(await this.orgPath("/templates"), {
             method: "POST",
@@ -198,20 +201,19 @@ export class SanboxClient {
     async listEvents(runId, afterEventId = 0, limit = 200, signal) {
         return this.request(`${await this.orgPath(`/runs/${encodeURIComponent(runId)}/events`)}?after_event_id=${afterEventId}&limit=${limit}`, { signal });
     }
-    async cancelRun(runId) {
-        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/cancel`), {
+    async stopRun(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/stop`), {
             method: "POST",
             body: "{}"
         });
     }
-    async resumeRun(runId) {
-        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/resume`), {
-            method: "POST",
-            body: "{}"
+    async deleteRun(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}`), {
+            method: "DELETE"
         });
     }
-    async pauseRun(runId) {
-        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/pause`), {
+    async resumeRun(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/resume`), {
             method: "POST",
             body: "{}"
         });

package/dist/args.js

@@ -15,9 +15,10 @@ export const booleanFlags = new Set([
     "wait",
     "watch",
     "jsonl",
-    "cancel-on-interrupt",
+    "stop-on-interrupt",
     "verbose",
     "force",
+    "yes",
     "write",
     "overwrite",
     "open",

package/dist/cli.js

@@ -10,8 +10,8 @@ import { loginWithBrowser, openBrowser, revokeUserSession } from "./deviceLogin.
 import { CliError, commandAction, consoleAction } from "./errors.js";
 import { parseFileAccessExpiry } from "./fileAccess.js";
 import { previewInputs } from "./inputs.js";
-import { printError, printJsonlError, printRun, printSuccess, publicRun, publicRunPayload } from "./output.js";
-import { createRun, isTerminalRun, readTasks, runPool, stableBatchId, waitForRun, waitForSandboxState } from "./runs.js";
+import { isoUtcTimestamp, printError, printJsonlError, printRun, printSuccess, publicRun, publicRunPayload } from "./output.js";
+import { createRun, isTerminalRun, runSucceeded, readTasks, runPool, stableBatchId, waitForRun, waitForRunState } from "./runs.js";
 import { version } from "./version.js";
 import { WatchInterruptedError, watchRun } from "./watch.js";
 import { openSSH, runSSHProxy } from "./ssh.js";
@@ -41,8 +41,10 @@ Commands:
   sanbox templates get <template-id> [--json]
   sanbox templates validate <template-id> [--json]
   sanbox templates create --name "..." --model-provider <provider-id> --model <model-id> [--harness opencode|hermes|browser-use] [--mode task|computer] [--channel email|telegram] [--browser-domain <hostname>] [--llm-budget-usd <amount>] [--json]
+  sanbox templates delete <template-id> --force [--json]
   sanbox run "task" --template <template-id> [--email-address <address>] [--telegram-bot-token <token>] [--telegram-allowed-user <id>] [--input <path>] [--wait | --watch] [--json | --jsonl]
   sanbox run --task "..." --template <template-id> [--email-address <address>] [--telegram-bot-token <token>] [--telegram-allowed-user <id>] [--input <path>] [--wait | --watch] [--json | --jsonl]
+  sanbox run --template <service-template-id> [--email-address <address>] [--telegram-bot-token <token>] [--telegram-allowed-user <id>] [--json]
   sanbox batch --tasks tasks.json --template <template-id> [--input <path>] [--max-parallel 5] [--wait] [--json]
   sanbox runs list [--limit 50] [--json]
   sanbox runs get <run-id> [--json]
@@ -52,10 +54,10 @@ Commands:
   sanbox runs shares <run-id> [--json]
   sanbox runs unshare <run-id> <access-point-id> [--json]
   sanbox runs download <run-id> --output <directory> [--artifact <path>] [--overwrite] [--json]
-  sanbox runs watch <run-id> [--after-event-id 0] [--view activity|logs|compact] [--jsonl]
-  sanbox runs cancel <run-id> [--json]
+  sanbox runs watch <run-id> [--after-event-id 0] [--view activity|logs|compact] [--stop-on-interrupt] [--jsonl]
+  sanbox runs stop <run-id> [--wait] [--json]
   sanbox runs resume <run-id> [--wait] [--json]
-  sanbox runs pause <run-id> [--wait] [--json]
+  sanbox runs delete <run-id> --yes [--json]
   sanbox runs supabase authorize <run-id> [--open] [--return-url <https-url>] [--json]
   sanbox opencode connect <run-id> [--expires 1h] [--json]
   sanbox opencode connections list <run-id> [--json]
@@ -92,8 +94,10 @@ const runHelp = `Sanbox run
 Usage:
   sanbox run "Review these files" --template <template-id> --input report.pdf --input data/ --wait
   sanbox run --task "Review these files" --template <template-id> --input report.pdf --wait --json
+  sanbox run --template <service-template-id> --json
 
 Options:
+  --task <instruction>          Required for task templates; optional for service templates.
   --input <path>                File, directory, or glob to upload. Repeatable.
   --template <id>               Template id or slug. Required unless SANBOX_TEMPLATE or project config sets it.
   --external-run-id <id>        Idempotency key for retries.
@@ -102,12 +106,12 @@ Options:
   --telegram-bot-token <token> Optional Telegram bot token; SANBOX_TELEGRAM_BOT_TOKEN is also supported.
   --telegram-allowed-user <id> Numeric Telegram user allowed to reach this run. Repeatable.
   --dry-run                     Preview included files without creating a run.
-  --wait                        Poll until terminal status.
-  --watch                       Stream activity until terminal status.
+  --wait                        Poll until a terminal run state.
+  --watch                       Stream activity until a terminal run state.
   --jsonl                       Stream one versioned activity event per line. Implies --watch.
-  --view <name>                 activity, logs, or compact. Default: activity.
+  --view <name>                 activity, compact, or historical logs. Default: activity.
   --after-event-id <id>         Resume after an event cursor. Default: 0.
-  --cancel-on-interrupt         Request run cancellation when Ctrl-C is pressed.
+  --stop-on-interrupt           Request Stop when Ctrl-C is pressed.
   --json                        Print JSON.
 `;
 const runsSupabaseHelp = `Sanbox Supabase run authorization
@@ -160,6 +164,7 @@ Usage:
   sanbox templates get <template-id> [--json]
   sanbox templates validate <template-id> [--json]
   sanbox templates create --name "Code review" --model-provider <provider-id> --model <model-id> [--harness opencode|hermes|browser-use] [--mode task|computer] [--browser-domain <hostname>] [--llm-budget-usd <amount>] [--json]
+  sanbox templates delete <template-id> --force [--json]
 
 Template creation requires an exact provider id and that provider's exact model id.
 LiteLLM budgets are optional USD amounts and apply separately to each run.
@@ -172,6 +177,7 @@ or Anthropic and at least one repeatable --browser-domain hostname or leading wi
 Optional controls: --browser-max-steps, --browser-step-timeout-seconds,
 --browser-vision-mode auto|always|never, --browser-viewport WIDTHxHEIGHT,
 --browser-download-policy allow|deny, and --browser-additional-instructions.
+Deleting a template requires --force. Existing runs and their retained sandboxes are preserved.
 `;
 const agentInstructions = `# Operate Sanbox Autonomously
 
@@ -225,7 +231,8 @@ sanbox run "Investigate one focused task and write output/report.md" \\
 
 Reuse the same --external-run-id after ambiguous failures. Retry network errors, HTTP 429, HTTP 5xx,
 and workspace_busy with bounded backoff. Do not retry other 4xx errors unless next_actions directs
-recovery. Terminal statuses are completed, failed, and canceled.
+recovery. A run is inactive when state is stopped; inspect latest_execution.outcome for the most
+recent bounded execution outcome.
 
 Recover and retrieve results:
 \`\`\`bash
@@ -254,20 +261,20 @@ Manage the retained sandbox independently of its agent harness:
 sanbox runs get <run-id> --json
 sanbox runs resume <run-id> --wait --json
 sanbox runs share <run-id> --expires 1h --json
-sanbox runs pause <run-id> --wait --json
+sanbox runs stop <run-id> --wait --json
+sanbox runs delete <run-id> --yes --json
 \`\`\`
 
-Resume restores the latest Firecracker snapshot without starting an agent command. It creates an
-exclusive manual lease and leaves the sandbox running until pause snapshots it again. Do not submit
-agent work while the manual lease is active. Before resume, require sandbox_state: "paused" and a
-positive snapshot_generation.
+Stop terminates compute and durably syncs the workspace without retaining RAM or VM state. Resume
+fresh-boots the pinned runtime artifact with that workspace; it does not restore process state or
+silently replay a finished task. Delete permanently removes the workspace after archiving usage.
 
 For independent fan-out, use \`sanbox batch\` with a stable external_run_id per task and keep the
 client alive until submission completes.
 
-Do not claim completion until the run is completed and required artifacts are downloaded and verified.
-Report run/external/template IDs, status, sandbox state, snapshot
-generation, artifact paths/digests, and blockers. The CLI excludes common secrets by default; add
+Do not claim completion until state is stopped, latest_execution.outcome is completed, and required
+artifacts are downloaded and verified. Report run/external/template IDs, run state, execution outcome, workspace save time,
+artifact paths/digests, and blockers. The CLI excludes common secrets by default; add
 .sanboxignore for project rules.
 `;
 const cwd = () => process.cwd();
@@ -446,6 +453,7 @@ const flagSets = {
     "templates.list": commonFlags,
     "templates.get": commonFlags,
     "templates.validate": commonFlags,
+    "templates.delete": [...commonFlags, "force"],
     "templates.create": [
         ...commonFlags,
         "name",
@@ -468,7 +476,7 @@ const flagSets = {
         ...commonFlags, "task", "input", "template", "external-run-id", "email-address",
         "supabase-user-id",
         "telegram-bot-token", "telegram-allowed-user",
-        "dry-run", "wait", "watch", "jsonl", "view", "after-event-id", "cancel-on-interrupt",
+        "dry-run", "wait", "watch", "jsonl", "view", "after-event-id", "stop-on-interrupt",
         "poll-interval-ms", "event-page-size", "timeout-seconds", "verbose"
     ],
     batch: [
@@ -484,12 +492,12 @@ const flagSets = {
     "runs.unshare": commonFlags,
     "runs.download": [...commonFlags, "output", "artifact", "overwrite"],
     "runs.watch": [
-        ...commonFlags, "after-event-id", "view", "jsonl", "cancel-on-interrupt",
+        ...commonFlags, "after-event-id", "view", "jsonl", "stop-on-interrupt",
         "poll-interval-ms", "event-page-size", "timeout-seconds"
     ],
-    "runs.cancel": commonFlags,
+    "runs.stop": [...commonFlags, "wait", "poll-interval-ms", "timeout-seconds"],
+    "runs.delete": [...commonFlags, "yes"],
     "runs.resume": [...commonFlags, "wait", "poll-interval-ms", "timeout-seconds"],
-    "runs.pause": [...commonFlags, "wait", "poll-interval-ms", "timeout-seconds"],
     "runs.supabase": [...commonFlags, "open", "return-url"],
     "opencode.connect": [...commonFlags, "expires"],
     "opencode.connections": commonFlags,
@@ -598,6 +606,7 @@ const validatePositionals = (command, flags) => {
         "templates.list": 2,
         "templates.get": 3,
         "templates.validate": 3,
+        "templates.delete": 3,
         "templates.create": 2,
         batch: 1,
         "runs.list": 2,
@@ -609,9 +618,9 @@ const validatePositionals = (command, flags) => {
         "runs.unshare": 4,
         "runs.download": 3,
         "runs.watch": 3,
-        "runs.cancel": 3,
+        "runs.stop": 3,
+        "runs.delete": 3,
         "runs.resume": 3,
-        "runs.pause": 3,
         "runs.supabase": 4,
         "opencode.connect": 3,
         "opencode.connections": 5,
@@ -658,7 +667,7 @@ const watchRunWithOutput = async (client, runId, flags, initialPayload) => {
     const onInterrupt = () => controller.abort();
     process.once("SIGINT", onInterrupt);
     if (!jsonl)
-        process.stdout.write(`Watching run ${runId}. Ctrl-C detaches without canceling.\n`);
+        process.stdout.write(`Watching run ${runId}. Ctrl-C detaches without stopping.\n`);
     try {
         return await watchRun(client, runId, {
             afterEventId: integerFlag(flags, "after-event-id", 0, 0, Number.MAX_SAFE_INTEGER),
@@ -680,9 +689,9 @@ const watchRunWithOutput = async (client, runId, flags, initialPayload) => {
     catch (error) {
         if (!(error instanceof WatchInterruptedError))
             throw error;
-        if (hasFlag(flags, "cancel-on-interrupt")) {
-            await client.cancelRun(runId);
-            process.stderr.write(`Cancellation requested for run ${runId}.\n`);
+        if (hasFlag(flags, "stop-on-interrupt")) {
+            await client.stopRun(runId);
+            process.stderr.write(`Stop requested for run ${runId}.\n`);
         }
         else {
             process.stderr.write(`Detached from run ${runId}; the run is still active.\n`);
@@ -720,8 +729,6 @@ const commandRun = async (command, flags) => {
         throw new CliError("conflicting_arguments", "Use either --task or a positional task, not both.");
     }
     const task = runTask(command, flags);
-    if (!task)
-        throw new Error("--task or a positional task is required.");
     if (hasFlag(flags, "wait") && wantsWatch(flags)) {
         throw new Error("--wait cannot be combined with --watch or --jsonl.");
     }
@@ -765,7 +772,7 @@ const commandRun = async (command, flags) => {
     try {
         payload = await createRun(client, {
             cwd: cwd(),
-            instruction: task,
+            instruction: task || undefined,
             inputs: flagList(flags, "input"),
             externalRunId: flagString(flags, "external-run-id") || undefined,
             supabaseUserId: supabaseUserId || undefined,
@@ -785,7 +792,7 @@ const commandRun = async (command, flags) => {
         payload = watched;
         if (!hasFlag(flags, "jsonl"))
             printRun(payload);
-        if (isTerminalRun(payload.run) && payload.run.status !== "completed")
+        if (isTerminalRun(payload.run) && !runSucceeded(payload.run))
             process.exitCode = 2;
         return;
     }
@@ -803,7 +810,7 @@ const commandRun = async (command, flags) => {
     }
     else
         printRun(payload);
-    if (hasFlag(flags, "wait") && isTerminalRun(payload.run) && payload.run.status !== "completed")
+    if (hasFlag(flags, "wait") && isTerminalRun(payload.run) && !runSucceeded(payload.run))
         process.exitCode = 2;
 };
 const commandBatch = async (flags) => {
@@ -850,7 +857,7 @@ const commandBatch = async (flags) => {
         printSuccess("batch.create", output, jsonContext(client));
     else
         results.forEach(printRun);
-    if (wait && results.some((result) => result.run.status !== "completed"))
+    if (wait && results.some((result) => !runSucceeded(result.run)))
         process.exitCode = 2;
 };
 const commandAuthCheck = async (flags) => {
@@ -1013,7 +1020,7 @@ const commandAnthropicEnvironments = async (command, flags) => {
         for (const environment of payload.environments) {
             process.stdout.write(`${environment.environment_id}\t${environment.status}` +
                 `\tworker=${environment.assigned_worker_id || "unassigned"}` +
-                `\tverified=${environment.last_verified_at || "never"}\n`);
+                `\tverified=${environment.last_verified_at ? isoUtcTimestamp(environment.last_verified_at) : "never"}\n`);
         }
         return;
     }
@@ -1033,7 +1040,7 @@ const commandAnthropicEnvironments = async (command, flags) => {
         const environment = payload.environment;
         process.stdout.write(`${environment.environment_id} ${environment.status}` +
             ` worker=${environment.assigned_worker_id || "unassigned"}` +
-            ` verified=${environment.last_verified_at || "never"}\n`);
+            ` verified=${environment.last_verified_at ? isoUtcTimestamp(environment.last_verified_at) : "never"}\n`);
         return;
     }
     if (action === "connect") {
@@ -1192,6 +1199,9 @@ const commandTemplates = async (command, flags) => {
         if (harness === "opencode" && mode === "computer" && llmBudgetUsd !== undefined) {
             throw new CliError("opencode_computer_budget_unsupported", "OpenCode Computer templates do not support --llm-budget-usd yet.");
         }
+        if (modelProvider === "custom" && llmBudgetUsd !== undefined) {
+            throw new CliError("custom_provider_budget_unsupported", "Custom OpenAI Proxy providers do not support --llm-budget-usd yet.");
+        }
         const channels = [...new Set(flagList(flags, "channel").map((value) => value.trim()).filter(Boolean))];
         if (channels.some((channel) => channel !== "email" && channel !== "telegram")) {
             throw new CliError("invalid_hermes_channels", "--channel must be email or telegram.");
@@ -1212,8 +1222,9 @@ const commandTemplates = async (command, flags) => {
             modelProvider !== "openai" &&
             modelProvider !== "anthropic" &&
             modelProvider !== "google" &&
-            modelProvider !== "hetzner") {
-            throw new CliError("browser_use_provider_unsupported", "Browser Use templates require --model-provider openai, anthropic, google, or hetzner.");
+            modelProvider !== "hetzner" &&
+            modelProvider !== "custom") {
+            throw new CliError("browser_use_provider_unsupported", "Browser Use templates require --model-provider openai, anthropic, google, hetzner, or custom.");
         }
         const browserDomains = harness === "browser-use"
             ? parseBrowserDomains(flagList(flags, "browser-domain"))
@@ -1280,7 +1291,39 @@ const commandTemplates = async (command, flags) => {
             `${payload.template.llm_budget_usd ? ` budget=$${payload.template.llm_budget_usd}/run` : ""}\n`);
         return;
     }
-    throw new CliError("templates_action_required", "templates requires an action: list, get, validate, or create.");
+    if (action === "delete") {
+        const id = requiredPositional(command[2], "template_id_required", "templates delete requires a template id or slug.");
+        if (!hasFlag(flags, "force")) {
+            throw new CliError("confirmation_required", "templates delete requires --force.", {
+                details: { template_id: id },
+                nextActions: [commandAction(["sanbox", "templates", "delete", id, "--force", "--json"], "Delete the template from this organization while preserving existing runs.")]
+            });
+        }
+        let payload;
+        try {
+            payload = await client.deleteTemplate(id);
+        }
+        catch (error) {
+            if (error instanceof SanboxApiError) {
+                throw new CliError(error.code, error.message, {
+                    status: error.status,
+                    details: { template_id: id },
+                    nextActions: error.code === "template_not_found"
+                        ? [commandAction(["sanbox", "templates", "list", "--json"], "List templates available to the API key's organization.")]
+                        : []
+                });
+            }
+            throw error;
+        }
+        const nextActions = [commandAction(["sanbox", "templates", "list", "--json"], "Confirm that the template is no longer available for new runs.")];
+        if (hasFlag(flags, "json")) {
+            printSuccess("templates.delete", payload, jsonContext(client), nextActions);
+            return;
+        }
+        process.stdout.write(`deleted ${payload.template_id}\n`);
+        return;
+    }
+    throw new CliError("templates_action_required", "templates requires an action: list, get, validate, create, or delete.");
 };
 const commandRuns = async (command, flags) => {
     const client = makeClient(flags);
@@ -1295,7 +1338,7 @@ const commandRuns = async (command, flags) => {
             return;
         }
         for (const run of payload.runs) {
-            process.stdout.write(`${run.id}\t${run.status}\t${run.created_at}\t${run.instruction.replace(/\s+/g, " ").slice(0, 100)}\n`);
+            process.stdout.write(`${run.id}\t${run.state}\t${isoUtcTimestamp(run.created_at)}\t${run.instruction.replace(/\s+/g, " ").slice(0, 100)}\n`);
         }
         return;
     }
@@ -1367,7 +1410,7 @@ const commandRuns = async (command, flags) => {
             return;
         }
         for (const accessPoint of payload.access_points) {
-            process.stdout.write(`${accessPoint.id}\t${accessPoint.status}\t${accessPoint.expires_at}\t${accessPoint.name}\n`);
+            process.stdout.write(`${accessPoint.id}\t${accessPoint.status}\t${isoUtcTimestamp(accessPoint.expires_at)}\t${accessPoint.name}\n`);
         }
         return;
     }
@@ -1435,24 +1478,26 @@ const commandRuns = async (command, flags) => {
             return;
         if (!hasFlag(flags, "jsonl"))
             printRun(payload);
-        if (isTerminalRun(payload.run) && payload.run.status !== "completed")
+        if (isTerminalRun(payload.run) && !runSucceeded(payload.run))
             process.exitCode = 2;
         return;
     }
-    if (action === "cancel") {
-        const payload = await client.cancelRun(runId);
+    if (action === "delete") {
+        if (!hasFlag(flags, "yes")) {
+            throw new CliError("confirmation_required", "Run deletion permanently removes its workspace. Re-run with --yes.");
+        }
+        const payload = await client.deleteRun(runId);
         if (hasFlag(flags, "json"))
-            printSuccess("runs.cancel", publicRunPayload(payload), jsonContext(client));
+            printSuccess("runs.delete", publicRunPayload(payload), jsonContext(client));
         else
-            printRun(payload);
+            process.stdout.write(`deletion requested for run ${runId}\n`);
         return;
     }
-    if (action === "resume" || action === "pause") {
-        const submitted = action === "resume"
-            ? await client.resumeRun(runId)
-            : await client.pauseRun(runId);
+    if (action === "stop" || action === "resume") {
+        const submitted = action === "resume" ? await client.resumeRun(runId) : await client.stopRun(runId);
+        const target = action === "resume" ? "running" : "stopped";
         const payload = hasFlag(flags, "wait")
-            ? await waitForSandboxState(client, runId, action === "resume" ? "running" : "paused", {
+            ? await waitForRunState(client, runId, target, {
                 pollIntervalMs: integerFlag(flags, "poll-interval-ms", 2000, 250, 60_000),
                 timeoutSeconds: integerFlag(flags, "timeout-seconds", 1800, 1, 604_800)
             })
@@ -1464,7 +1509,7 @@ const commandRuns = async (command, flags) => {
             printRun(payload);
         }
         else {
-            process.stdout.write(`sandbox ${action} requested for run ${runId}\n`);
+            process.stdout.write(`${action} requested for run ${runId}\n`);
         }
         return;
     }
@@ -1486,7 +1531,7 @@ const commandOpenCode = async (command, flags) => {
             ]);
             return;
         }
-        process.stdout.write(`URL ${payload.url}\nTOKEN ${payload.access_token}\nEXPIRES ${payload.connection.expires_at}\n`);
+        process.stdout.write(`URL ${payload.url}\nTOKEN ${payload.access_token}\nEXPIRES ${isoUtcTimestamp(payload.connection.expires_at)}\n`);
         return;
     }
     if (action === "connections") {
@@ -1502,7 +1547,7 @@ const commandOpenCode = async (command, flags) => {
                 return;
             }
             for (const connection of payload.connections) {
-                process.stdout.write(`${connection.id}\t${connection.status}\t${connection.expires_at}\t${connection.token_prefix}\n`);
+                process.stdout.write(`${connection.id}\t${connection.status}\t${isoUtcTimestamp(connection.expires_at)}\t${connection.token_prefix}\n`);
             }
             return;
         }

package/dist/output.js

@@ -1,5 +1,11 @@
 import { CliError } from "./errors.js";
 import { SanboxApiError } from "./api.js";
+// Human-readable CLI output uses one canonical ISO 8601 UTC representation.
+// Structured JSON output preserves the API payload unchanged.
+export const isoUtcTimestamp = (value) => {
+    const date = new Date(value);
+    return Number.isFinite(date.getTime()) ? date.toISOString() : value;
+};
 export const printJson = (value) => {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 };
@@ -73,18 +79,21 @@ export const publicRunPayload = (payload) => ({
 });
 export const summarizeRun = (payload) => {
     const { run } = payload;
+    const execution = run.latest_execution;
     const templateId = run.template_id || run.workload_id;
     const selection = [
         templateId ? `template=${templateId}` : "",
         run.provider_id ? `provider=${run.provider_id}` : "",
         run.model_id ? `model=${run.model_id}` : "",
-        run.sandbox_state ? `sandbox=${run.sandbox_state}` : "",
-        run.snapshot_generation ? `snapshot=${run.snapshot_generation}` : "",
+        `state=${run.state}`,
+        execution?.outcome
+            ? `result=${execution.outcome}`
+            : "",
         run.email?.address ? `email=${run.email.address}` : run.email ? `email=${run.email.status}` : "",
         run.channels?.telegram.enabled ? "telegram=enabled" : "",
         run.supabase ? `supabase=${run.supabase.status}` : ""
     ].filter(Boolean).join(" ");
-    return `${run.id} ${run.status}${selection ? ` ${selection}` : ""}${run.exit_code === null ? "" : ` exit=${run.exit_code}`}${run.error ? ` error=${run.error}` : ""}`;
+    return `${run.id}${selection ? ` ${selection}` : ""}${execution?.exit_code == null ? "" : ` exit=${execution.exit_code}`}${execution?.error ? ` error=${execution.error}` : ""}`;
 };
 export const printRun = (payload) => {
     process.stdout.write(`${summarizeRun(payload)}\n`);

package/dist/runs.js

@@ -2,8 +2,8 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { buildInputBundle } from "./inputs.js";
-const terminalStatuses = new Set(["completed", "failed", "canceled"]);
-export const isTerminalRun = (run) => terminalStatuses.has(run.status);
+export const isTerminalRun = (run) => run.state === "stopped" || run.state === "deleting" || run.state === "deleted";
+export const runSucceeded = (run) => run.latest_execution?.outcome === "completed";
 export const waitForRun = async (client, runId, options = {}) => {
     const pollIntervalMs = options.pollIntervalMs ?? 2000;
     const deadline = Date.now() + (options.timeoutSeconds ?? 1800) * 1000;
@@ -16,20 +16,23 @@ export const waitForRun = async (client, runId, options = {}) => {
     }
     return payload;
 };
-export const waitForSandboxState = async (client, runId, target, options = {}) => {
+export const waitForRunState = async (client, runId, target, options = {}) => {
     const pollIntervalMs = options.pollIntervalMs ?? 2000;
     const deadline = Date.now() + (options.timeoutSeconds ?? 1800) * 1000;
     let payload = await client.getRun(runId);
-    while (payload.run.sandbox_state !== target) {
-        if (payload.run.sandbox_state === "error" || payload.run.sandbox_state === "deleted") {
-            throw new Error(`Sandbox entered ${payload.run.sandbox_state} while waiting for ${target}.`);
+    while (payload.run.state !== target) {
+        if (payload.run.state === "deleting" || payload.run.state === "deleted") {
+            throw new Error("Run is being deleted.");
         }
-        if (target === "running" && payload.run.sandbox_state === "paused") {
-            throw new Error("Sandbox returned to paused before the manual lease became ready.");
-        }
-        if (Date.now() > deadline) {
-            throw new Error(`Timed out waiting for sandbox ${runId} to become ${target}.`);
+        if (target === "running" && payload.run.state === "stopped") {
+            const lifecycleMessage = typeof payload.run.lifecycle_error?.message === "string"
+                ? payload.run.lifecycle_error.message
+                : null;
+            const detail = lifecycleMessage || payload.run.latest_execution?.error;
+            throw new Error(`Run ${runId} stopped before it became running${detail ? `: ${detail}` : "."}`);
         }
+        if (Date.now() > deadline)
+            throw new Error(`Timed out waiting for run ${runId} to become ${target}.`);
         await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
         payload = await client.getRun(runId);
     }
@@ -49,7 +52,7 @@ export const createRun = async (client, options) => {
     return client.createRun({
         external_run_id: options.externalRunId,
         workload_id: options.templateId,
-        instruction: options.instruction,
+        ...(options.instruction ? { instruction: options.instruction } : {}),
         ...(options.supabaseUserId ? { supabase_user_id: options.supabaseUserId } : {}),
         ...(options.emailAddress ? { email_address: options.emailAddress } : {}),
         ...(options.telegramBotToken ? {

package/dist/version.js

@@ -1 +1 @@
-export const version = "0.0.11";
+export const version = "0.0.13";

package/dist/watch.js

@@ -1,6 +1,6 @@
 import { SanboxApiError } from "./api.js";
-const terminalStatuses = new Set(["completed", "failed", "canceled"]);
-const terminalEventKinds = new Set(["run.completed", "run.failed", "run.canceled"]);
+const terminalStates = new Set(["stopped", "deleting", "deleted"]);
+const terminalEventKinds = new Set(["run.completed", "run.failed", "run.stopped"]);
 const retryableNetworkCodes = new Set(["ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT", "EAI_AGAIN", "ENETUNREACH"]);
 export class WatchInterruptedError extends Error {
     constructor() {
@@ -37,7 +37,7 @@ const assertActive = (signal, deadline, now, runId) => {
     if (now() >= deadline)
         throw new Error(`Timed out watching run ${runId}.`);
 };
-export const isTerminalStatus = (status) => terminalStatuses.has(status);
+export const isTerminalStatus = (state) => terminalStates.has(state);
 export const watchEventsUntil = async (client, runId, options) => {
     const pageSize = Math.max(1, Math.min(500, Math.floor(options.pageSize ?? 200)));
     const pollIntervalMs = Math.max(1, Math.floor(options.pollIntervalMs ?? 2000));
@@ -156,7 +156,7 @@ export const watchRun = async (client, runId, options) => {
             fetchAnotherPage = reportedMore && cursor > previousCursor;
         }
         const payload = await request(() => client.getRun(runId, options.signal));
-        if (isTerminalStatus(payload.run.status)) {
+        if (isTerminalStatus(payload.run.state)) {
             emptyTerminalReads = deliveredThisCycle === 0 ? emptyTerminalReads + 1 : 0;
             const requiredEmptyReads = sawTerminalEvent ? 1 : 2;
             if (emptyTerminalReads >= requiredEmptyReads)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanlabs/sanbox-cli",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "private": false,
   "repository": {
     "type": "git",