@sanlabs/sanbox-cli 0.0.10 → 0.0.11

package/README.md

@@ -15,9 +15,11 @@ 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.11 adds 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 +84,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
@@ -244,22 +258,57 @@ access until Pause creates the next snapshot generation. Before resuming, requir
 `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.
 
-## 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 sandbox can
+still be resumed manually for inspection when a snapshot exists.
+
+## 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/api.js

@@ -231,6 +231,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/cli.js

@@ -40,7 +40,7 @@ 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 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]
@@ -57,6 +57,9 @@ Commands:
   sanbox runs resume <run-id> [--wait] [--json]
   sanbox runs pause <run-id> [--wait] [--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 +69,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:
@@ -144,10 +159,12 @@ 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]
 
 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
@@ -435,6 +452,7 @@ const flagSets = {
         "model-provider",
         "model",
         "harness",
+        "mode",
         "llm-budget-usd",
         "web-access",
         "channel",
@@ -473,6 +491,8 @@ const flagSets = {
     "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 +510,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 +529,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 +571,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)
@@ -590,6 +613,8 @@ const validatePositionals = (command, flags) => {
         "runs.resume": 3,
         "runs.pause": 3,
         "runs.supabase": 4,
+        "opencode.connect": 3,
+        "opencode.connections": 5,
         ssh: 2,
         "ssh-proxy": 1,
         login: 1,
@@ -1144,6 +1169,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 +1189,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 +1230,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 +1261,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;
@@ -1427,6 +1470,57 @@ const commandRuns = async (command, flags) => {
     }
     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 ${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${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 +1768,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 +1797,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 +1849,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/version.js

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

package/package.json

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