@sanlabs/sanbox-cli 0.0.10 → 0.0.12

package/README.md

@@ -15,9 +15,14 @@ installed_cli_version="$(sanbox --version)"
 test "$installed_cli_version" = "$latest_cli_version"
 ```
 
-Always use the latest published CLI. CLI 0.0.10 adds per-run Hermes email and Telegram channels,
-Supabase user authorization, and removes the retired run-chat commands.
-CLI 0.0.9 added user login for private SSH access to running Hermes Computers.
+Always use the latest published CLI. CLI 0.0.12 adopts 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.
 CLI 0.0.6 added Anthropic self-hosted environment inspection and administration.
 
 ## Configure
@@ -82,8 +87,20 @@ sanbox doctor --json
 
 Model IDs are provider-scoped. The CLI never guesses or silently substitutes a provider, model, or template.
 For waited task runs, choose a template with `runnable: true`, `template_type: "runner"`, and
-`runner_config.harness: "opencode"` or `"browser-use"`. Browser Use is for one-shot web tasks whose
-target domains are already approved. Hermes service templates are always-on. A Hermes template
+`runner_config.harness: "opencode"` or `"browser-use"`. OpenCode remains the default one-shot mode,
+while OpenCode Computer runs a retained private OpenCode server:
+
+```bash
+sanbox templates create \
+  --name "OpenCode Computer" \
+  --harness opencode \
+  --mode computer \
+  --model-provider openai \
+  --model '<model-id>'
+```
+
+Existing templates keep their current names, IDs, slugs, and task behavior. Browser Use is for one-shot
+web tasks whose target domains are already approved. Hermes service templates are always-on. A Hermes template
 declares which optional channels its runs may activate:
 
 ```bash
@@ -99,6 +116,15 @@ 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,
@@ -186,7 +212,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
 
@@ -229,37 +255,75 @@ 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 Hermes Computer
+## SSH Into A Running Sandbox
 
 ```bash
 sanbox login
 sanbox ssh <run-id>
 ```
 
-The run must be a currently running Hermes Computer created from the SSH-capable template artifact.
+The run must be a currently running OpenCode run or Hermes Computer created from an SSH-capable
+artifact.
 The signed-in user must own the run or be an organization admin. The command uses your local OpenSSH
 client, but it does not expose the microVM on a public IP or port. The CLI generates a temporary
 Ed25519 identity, pins the microVM's runtime host key, and tunnels the SSH stream over a one-time
 authenticated WebSocket. The temporary key is deleted when the connection closes, and the saved
 user token is not passed to the OpenSSH child process.
 
-OpenCode and Browser Use runs are one-shot agent executions. Create a new run for additional agent
-work. A persisted sandbox can still be resumed manually for inspection when a snapshot exists.
+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 workspace can
+still be fresh-booted manually for inspection after the run stops.
+
+## Connect The OpenCode SDK
+
+Create a short-lived connection for a currently running OpenCode Computer:
+
+```bash
+sanbox opencode connect <run-id> --expires 1h --json
+sanbox opencode connections list <run-id> --json
+sanbox opencode connections revoke <run-id> <connection-id> --json
+```
+
+The create response contains `url`, `access_token`, and connection metadata. The plaintext token is
+returned only once, but it can authenticate all OpenCode SDK requests and SSE reconnects until it
+expires, is revoked, or the runtime session ends. Multiple connections can coexist. Organization API
+keys use their existing organization role and require member access or higher; no additional API-key
+or connection-token scopes are introduced.
+
+```ts
+import { createOpencodeClient } from "@opencode-ai/sdk"
+
+const client = createOpencodeClient({
+  baseUrl: connection.url,
+  headers: { Authorization: `Bearer ${connection.access_token}` },
+})
+
+const events = await client.event.subscribe()
+```
+
+Sanbox proxies the native HTTP and SSE API through its private Firecracker management path. The
+microVM never exposes an inbound port. Only security-sensitive OpenCode configuration,
+authentication, credential mutation, server-administration, raw PTY, and public-share routes are
+denied; core session, event, file, command, and session-shell APIs remain native. See
+[OpenCode SDK access](../docs/opencode-sdk-access.md) for the API and lifecycle contract.
 
 ## Batch Work
 

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: "{}"
         });
@@ -231,6 +233,18 @@ export class SanboxClient {
     async revokeFileAccessPoint(runId, accessPointId) {
         return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/file-access-points/${encodeURIComponent(accessPointId)}`), { method: "DELETE" });
     }
+    async listOpenCodeConnections(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/opencode-connections`));
+    }
+    async createOpenCodeConnection(runId, expiresInSeconds) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/opencode-connections`), {
+            method: "POST",
+            body: JSON.stringify({ expires_in_seconds: expiresInSeconds })
+        });
+    }
+    async revokeOpenCodeConnection(runId, connectionId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/opencode-connections/${encodeURIComponent(connectionId)}`), { method: "DELETE" });
+    }
     async downloadArtifact(runId, artifactPath) {
         return this.rawRequest(`${await this.orgPath(`/runs/${encodeURIComponent(runId)}/artifacts`)}?path=${encodeURIComponent(artifactPath)}`);
     }

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";
@@ -40,7 +40,8 @@ Commands:
   sanbox templates list [--json]
   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] [--channel email|telegram] [--browser-domain <hostname>] [--llm-budget-usd <amount>] [--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 batch --tasks tasks.json --template <template-id> [--input <path>] [--max-parallel 5] [--wait] [--json]
@@ -52,11 +53,14 @@ 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]
+  sanbox opencode connections revoke <run-id> <connection-id> [--json]
   sanbox ssh <run-id>
   sanbox init [--force]
   sanbox init agent [--write]
@@ -66,12 +70,24 @@ const sshHelp = `Sanbox SSH
 Usage:
   sanbox ssh <run-id>
 
-Opens the running Hermes Computer with your local OpenSSH client. Sanbox creates an ephemeral
-Ed25519 key, authorizes it for one connection, verifies the microVM host key, and tunnels SSH over
-the authenticated private management path. Run sanbox login first. The computer owner and
+Opens a running OpenCode run or Hermes Computer with your local OpenSSH client. Sanbox creates an
+ephemeral Ed25519 key, authorizes it for one connection, verifies the microVM host key, and tunnels
+SSH over the authenticated private management path. Run sanbox login first. The run owner and
 organization admins can connect; organization API keys cannot open interactive sessions. The guest
 does not expose port 22 publicly.
 `;
+const openCodeHelp = `Sanbox OpenCode SDK access
+
+Usage:
+  sanbox opencode connect <run-id> [--expires 1h] [--json]
+  sanbox opencode connections list <run-id> [--json]
+  sanbox opencode connections revoke <run-id> <connection-id> [--json]
+
+Creates short-lived bearer credentials for the native OpenCode SDK. The token is bound to one
+running OpenCode Computer and its current runtime session. Its plaintext value is returned only
+when created. Multiple connections may be active at once; each expires and can be revoked
+independently. Organization API keys require member access or higher.
+`;
 const runHelp = `Sanbox run
 
 Usage:
@@ -87,12 +103,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
@@ -144,10 +160,13 @@ Usage:
   sanbox templates list [--json]
   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] [--browser-domain <hostname>] [--llm-budget-usd <amount>] [--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.
+OpenCode defaults to --mode task. Use --mode computer for a retained private OpenCode server;
+per-run LiteLLM budgets are not available for that retained mode yet.
 Hermes templates are always-on computers. Use repeatable --channel email|telegram to select which
 channels runs may activate. Email and Telegram credentials are supplied only when creating a run.
 Browser Use templates run local headless Chromium inside a one-shot sandbox. They require OpenAI
@@ -155,6 +174,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
 
@@ -208,7 +228,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
@@ -237,20 +258,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();
@@ -429,12 +450,14 @@ const flagSets = {
     "templates.list": commonFlags,
     "templates.get": commonFlags,
     "templates.validate": commonFlags,
+    "templates.delete": [...commonFlags, "force"],
     "templates.create": [
         ...commonFlags,
         "name",
         "model-provider",
         "model",
         "harness",
+        "mode",
         "llm-budget-usd",
         "web-access",
         "channel",
@@ -450,7 +473,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: [
@@ -466,13 +489,15 @@ 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,
     ssh: ["api-url", "help"],
     "ssh-proxy": [],
     login: ["api-url", "json", "no-browser", "help"],
@@ -490,10 +515,13 @@ const commandKey = (command) => {
         return `auth.${command[1] || ""}`;
     if (command[0] === "runs" && command[1] === "supabase")
         return "runs.supabase";
+    if (command[0] === "opencode" && command[1] === "connections")
+        return "opencode.connections";
     if (command[0] === "model-providers" ||
         command[0] === "anthropic-environments" ||
         command[0] === "templates" ||
-        command[0] === "runs") {
+        command[0] === "runs" ||
+        command[0] === "opencode") {
         return `${command[0]}.${command[1] || ""}`;
     }
     if (command[0] === "init" && command[1] === "agent")
@@ -506,7 +534,7 @@ const requiredValueFlags = new Set([
     "telegram-bot-token", "telegram-allowed-user", "channel",
     "tasks", "max-parallel", "batch-id", "poll-interval-ms",
     "event-page-size", "timeout-seconds", "view", "after-event-id", "limit", "name",
-    "model-provider", "model", "harness", "llm-budget-usd",
+    "model-provider", "model", "harness", "mode", "llm-budget-usd",
     "browser-domain", "browser-max-steps", "browser-step-timeout-seconds",
     "browser-vision-mode", "browser-viewport", "browser-download-policy",
     "browser-additional-instructions", "expires", "output", "artifact"
@@ -548,7 +576,7 @@ const validateFlags = (command, flags) => {
     }
     const knownRoots = new Set([
         "auth", "context", "doctor", "model-providers", "anthropic-environments", "templates",
-        "run", "batch", "runs", "ssh", "ssh-proxy", "login", "logout", "init", "version"
+        "run", "batch", "runs", "opencode", "ssh", "ssh-proxy", "login", "logout", "init", "version"
     ]);
     const allowed = flagSets[key] ?? (knownRoots.has(command[0] || "") ? commonFlags : null);
     if (!allowed)
@@ -575,6 +603,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,
@@ -586,10 +615,12 @@ 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,
         ssh: 2,
         "ssh-proxy": 1,
         login: 1,
@@ -633,7 +664,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),
@@ -655,9 +686,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`);
@@ -760,7 +791,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;
     }
@@ -778,7 +809,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) => {
@@ -825,7 +856,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) => {
@@ -988,7 +1019,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;
     }
@@ -1008,7 +1039,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") {
@@ -1144,6 +1175,14 @@ const commandTemplates = async (command, flags) => {
         if (harness !== "opencode" && harness !== "hermes" && harness !== "browser-use") {
             throw new CliError("invalid_harness", "templates create --harness must be opencode, hermes, or browser-use.");
         }
+        const modeFlag = flagString(flags, "mode");
+        const mode = modeFlag || "task";
+        if (mode !== "task" && mode !== "computer") {
+            throw new CliError("invalid_opencode_mode", "templates create --mode must be task or computer.");
+        }
+        if (harness !== "opencode" && modeFlag) {
+            throw new CliError("opencode_mode_not_supported", "templates create --mode requires --harness opencode.");
+        }
         const budgetRaw = flagString(flags, "llm-budget-usd");
         const parsedBudgetUsd = budgetRaw ? Number(budgetRaw) : undefined;
         const llmBudgetUsd = parsedBudgetUsd === undefined
@@ -1156,6 +1195,9 @@ const commandTemplates = async (command, flags) => {
         if (harness === "hermes" && llmBudgetUsd !== undefined) {
             throw new CliError("hermes_budget_unsupported", "Always-on Hermes templates do not support --llm-budget-usd yet.");
         }
+        if (harness === "opencode" && mode === "computer" && llmBudgetUsd !== undefined) {
+            throw new CliError("opencode_computer_budget_unsupported", "OpenCode Computer templates 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.");
@@ -1194,6 +1236,7 @@ const commandTemplates = async (command, flags) => {
                 name,
                 provider_id: modelProvider,
                 model_id: model,
+                ...(harness === "opencode" && modeFlag ? { mode: mode } : {}),
                 ...(llmBudgetUsd === undefined ? {} : { llm_budget_usd: llmBudgetUsd }),
                 ...(harness === "browser-use" ? {
                     harness,
@@ -1224,11 +1267,17 @@ const commandTemplates = async (command, flags) => {
                 commandAction([
                     "sanbox",
                     "run",
-                    harness === "hermes" ? "<agent role and instructions>" : "<task>",
+                    harness === "hermes"
+                        ? "<agent role and instructions>"
+                        : harness === "opencode" && mode === "computer"
+                            ? "<computer role and instructions>"
+                            : "<task>",
                     "--template",
                     payload.template.id
-                ], harness === "hermes"
-                    ? "Start the always-on computer and activate only the channels this run needs."
+                ], harness === "hermes" || (harness === "opencode" && mode === "computer")
+                    ? harness === "hermes"
+                        ? "Start the always-on computer and activate only the channels this run needs."
+                        : "Start the retained OpenCode computer."
                     : "Create a run with the new template.")
             ]);
             return;
@@ -1237,7 +1286,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);
@@ -1252,7 +1333,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;
     }
@@ -1324,7 +1405,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;
     }
@@ -1392,24 +1473,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)
             })
@@ -1421,12 +1504,63 @@ 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;
     }
     throw new Error(`Unknown runs action: ${action}`);
 };
+const commandOpenCode = async (command, flags) => {
+    const client = makeClient(flags);
+    const action = command[1];
+    if (action === "connect") {
+        const runId = requiredPositional(command[2], "run_id_required", "opencode connect requires a run id.");
+        const expiresInSeconds = parseFileAccessExpiry(flagString(flags, "expires", "1h"));
+        if (expiresInSeconds > 24 * 60 * 60) {
+            throw new CliError("invalid_opencode_connection_expiry", "OpenCode connection expiry must be between 1 minute and 1 day.");
+        }
+        const payload = await client.createOpenCodeConnection(runId, expiresInSeconds);
+        if (hasFlag(flags, "json")) {
+            printSuccess("opencode.connect", payload, jsonContext(client), [
+                commandAction(["sanbox", "opencode", "connections", "revoke", runId, payload.connection.id, "--json"], "Revoke this OpenCode SDK connection.")
+            ]);
+            return;
+        }
+        process.stdout.write(`URL ${payload.url}\nTOKEN ${payload.access_token}\nEXPIRES ${isoUtcTimestamp(payload.connection.expires_at)}\n`);
+        return;
+    }
+    if (action === "connections") {
+        const connectionAction = command[2];
+        if (connectionAction === "list") {
+            const runId = requiredPositional(command[3], "run_id_required", "opencode connections list requires a run id.");
+            if (command[4]) {
+                throw new CliError("unexpected_argument", `Unexpected positional argument: ${command[4]}`);
+            }
+            const payload = await client.listOpenCodeConnections(runId);
+            if (hasFlag(flags, "json")) {
+                printSuccess("opencode.connections.list", payload, jsonContext(client));
+                return;
+            }
+            for (const connection of payload.connections) {
+                process.stdout.write(`${connection.id}\t${connection.status}\t${isoUtcTimestamp(connection.expires_at)}\t${connection.token_prefix}\n`);
+            }
+            return;
+        }
+        if (connectionAction === "revoke") {
+            const runId = requiredPositional(command[3], "run_id_required", "opencode connections revoke requires a run id.");
+            const connectionId = requiredPositional(command[4], "opencode_connection_id_required", "opencode connections revoke requires a connection id.");
+            const payload = await client.revokeOpenCodeConnection(runId, connectionId);
+            if (hasFlag(flags, "json")) {
+                printSuccess("opencode.connections.revoke", payload, jsonContext(client));
+                return;
+            }
+            process.stdout.write(`revoked ${payload.connection.id}\n`);
+            return;
+        }
+        throw new CliError("opencode_connections_action_required", "opencode connections requires an action: list or revoke.");
+    }
+    throw new CliError("opencode_action_required", "opencode requires an action: connect or connections.");
+};
 const commandDoctor = async (flags) => {
     const localConfig = readLocalConfig();
     const apiUrl = String(flags["api-url"] || process.env.SANBOX_API_URL || localConfig.api_url || defaultApiUrl).replace(/\/+$/, "");
@@ -1674,6 +1808,8 @@ const helpFor = (command) => {
         return anthropicEnvironmentsHelp;
     if (command[0] === "templates")
         return templatesHelp;
+    if (command[0] === "opencode")
+        return openCodeHelp;
     if (command[0] === "ssh")
         return sshHelp;
     return help;
@@ -1701,6 +1837,11 @@ const commandId = (command) => {
     }
     if (command[0] === "runs")
         return `runs.${command[1] || "unknown"}`;
+    if (command[0] === "opencode" && command[1] === "connections") {
+        return `opencode.connections.${command[2] || "unknown"}`;
+    }
+    if (command[0] === "opencode")
+        return `opencode.${command[1] || "unknown"}`;
     if (command[0] === "ssh" || command[0] === "ssh-proxy")
         return command[0];
     return command[0] || "help";
@@ -1748,6 +1889,8 @@ const main = async (command, flags) => {
         return commandBatch(flags);
     if (command[0] === "runs")
         return commandRuns(command, flags);
+    if (command[0] === "opencode")
+        return commandOpenCode(command, flags);
     if (command[0] === "ssh")
         return commandSSH(command, flags);
     if (command[0] === "ssh-proxy") {

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);
     }

package/dist/version.js

@@ -1 +1 @@
-export const version = "0.0.10";
+export const version = "0.0.12";

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.10",
+  "version": "0.0.12",
   "private": false,
   "repository": {
     "type": "git",