@sanlabs/sanbox-cli 0.0.12 → 0.0.14

package/README.md

@@ -15,7 +15,14 @@ installed_cli_version="$(sanbox --version)"
 test "$installed_cli_version" = "$latest_cli_version"
 ```
 
-Always use the latest published CLI. CLI 0.0.12 adopts the Stop, Resume, and Delete lifecycle,
+Always use the latest published CLI. CLI 0.0.14 adds repeatable `--allowed-model` options when
+creating OpenCode Computer templates and `sanbox run --model` to select a configured same-provider
+model at startup. The selected model is saved on the run and reused on Resume; SDK per-prompt
+switching does not change that saved startup default.
+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
@@ -96,9 +103,31 @@ sanbox templates create \
   --harness opencode \
   --mode computer \
   --model-provider openai \
-  --model '<model-id>'
+  --model '<default-model-id>' \
+  --allowed-model '<additional-model-id>'
 ```
 
+Repeat `--allowed-model` to make more models from the same provider available for native OpenCode
+SDK prompt switching. The default `--model` is included automatically. At template creation, Sanbox
+checks that each ID is in the organization's saved provider catalog; it does not infer model
+compatibility or availability. Later catalog changes do not block Computer startup or resume, even
+if the default model disappears. Configured IDs remain registered, and model errors surface when
+a prompt uses them.
+
+Choose a different startup model when creating an OpenCode Computer run:
+
+```bash
+sanbox run --template <computer-template-id> --model '<additional-model-id>' --json
+sanbox run "Inspect the repository" --template <computer-template-id> --model '<additional-model-id>' --json
+```
+
+`sanbox run --model` accepts an exact ID from the template's configured models (`allowed_model_ids`),
+using the template's provider. Omit it to use the template default. The selection is saved on the run;
+`sanbox runs resume <run-id>` reuses it without another `--model` flag. Neither run creation nor SDK
+per-prompt switching changes the template default, and SDK switches do not update the run's saved
+startup model. This override is supported only for OpenCode Computer, not task or Hermes templates.
+An `external_run_id` retry with a different explicit model returns `idempotency_conflict`.
+
 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:
@@ -128,7 +157,8 @@ 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 \
@@ -151,6 +181,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/ \
@@ -163,8 +195,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
@@ -289,8 +331,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 workspace can
-still be fresh-booted manually for inspection after the run stops.
+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/args.js

@@ -3,6 +3,7 @@ const multiFlags = new Set([
     "include",
     "artifact",
     "channel",
+    "allowed-model",
     "telegram-allowed-user",
     "browser-domain"
 ]);

package/dist/cli.js

@@ -40,10 +40,11 @@ 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] [--mode task|computer] [--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] [--allowed-model <model-id>] [--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 "task" --template <template-id> [--model <model-id>] [--email-address <address>] [--telegram-bot-token <token>] [--telegram-allowed-user <id>] [--input <path>] [--wait | --watch] [--json | --jsonl]
+  sanbox run --task "..." --template <template-id> [--model <model-id>] [--email-address <address>] [--telegram-bot-token <token>] [--telegram-allowed-user <id>] [--input <path>] [--wait | --watch] [--json | --jsonl]
+  sanbox run --template <service-template-id> [--model <model-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]
@@ -93,10 +94,15 @@ 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
+  sanbox run --template <opencode-computer-template-id> --model <model-id> --json
+  sanbox run "Inspect the repository" --template <opencode-computer-template-id> --model <model-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.
+  --model <id>                  Startup model from the OpenCode Computer template's configured models.
   --external-run-id <id>        Idempotency key for retries.
   --supabase-user-id <id>       Supabase Auth user UUID expected during OAuth consent.
   --email-address <address>     Optional for Hermes computers; must use a listed AgentMail domain.
@@ -110,6 +116,10 @@ Options:
   --after-event-id <id>         Resume after an event cursor. Default: 0.
   --stop-on-interrupt           Request Stop when Ctrl-C is pressed.
   --json                        Print JSON.
+
+--model is supported only for OpenCode Computer, with or without an initial task.
+Omitting --model uses the template's default. The provider stays fixed to the template.
+The chosen startup model is saved on the run and reused on resume; SDK per-prompt switches do not change it.
 `;
 const runsSupabaseHelp = `Sanbox Supabase run authorization
 
@@ -160,13 +170,15 @@ 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] [--mode task|computer] [--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] [--allowed-model <model-id>] [--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.
+Use repeatable --allowed-model with OpenCode Computer to make additional models from the selected
+provider available for SDK prompt switching. --model remains the default and is included automatically.
 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
@@ -213,6 +225,13 @@ a Hermes service template for a waited task because it is always-on. Select auto
 template qualifies; otherwise ask the user. Provider credentials and template administration are
 console-only.
 
+For an explicitly requested OpenCode Computer, use a service template with harness opencode and
+execution_mode computer. The task is optional; omit --wait. Use sanbox run --model <model-id> to
+select an exact ID from the template's allowed_model_ids, keeping its provider unchanged. Omit
+--model to use the template default. The startup model is saved on the run and reused on Resume
+without re-specifying --model. SDK per-prompt switching changes neither the template default nor
+the run's saved startup model. This flag is not supported for task or Hermes templates.
+
 Use --json for request/response commands and --jsonl for streams. Parse the versioned envelope:
 schema_version, ok, command, context, data or error, and next_actions. Execute command actions as
 argv arrays, never shell strings. Exit 0 means command success, 1 local/API failure, 2 readiness or
@@ -313,7 +332,19 @@ const providerReadinessCodes = new Set([
     "model_not_found_for_provider",
     "template_provider_missing"
 ]);
-const runCreationError = (error, client, template) => {
+const runModelSelectionCodes = new Set([
+    "invalid_run_model",
+    "run_model_not_configured",
+    "run_model_override_not_supported"
+]);
+const runCreationError = (error, client, template, modelId) => {
+    if (error instanceof SanboxApiError && runModelSelectionCodes.has(error.code)) {
+        return new CliError(error.code, error.message, {
+            status: error.status,
+            details: { template_id: template.id, model_id: modelId },
+            nextActions: [error.code === "run_model_override_not_supported" ? commandAction(["sanbox", "run", "--help"], "Remove --model and retry. Startup model overrides require an OpenCode Computer template.") : commandAction(["sanbox", "templates", "get", template.id, "--json"], "Inspect the template's configured models. Omit --model to use its default.")]
+        });
+    }
     if (!(error instanceof SanboxApiError) || !runReadinessCodes.has(error.code))
         return error;
     const nextActions = [
@@ -345,7 +376,7 @@ const templateCreationError = (error, client, providerId, modelId) => {
         return new CliError(error.code, error.message, {
             status: error.status,
             details: { provider_id: providerId, model_id: modelId },
-            nextActions: [commandAction(["sanbox", "model-providers", "models", providerId, "--json"], "List exact selectable and non-selectable model ids exposed by the selected provider.")]
+            nextActions: [commandAction(["sanbox", "model-providers", "models", providerId, "--json"], "List exact model IDs in the selected provider's catalog.")]
         });
     }
     if (error.code === "template_name_conflict") {
@@ -458,6 +489,7 @@ const flagSets = {
         "model",
         "harness",
         "mode",
+        "allowed-model",
         "llm-budget-usd",
         "web-access",
         "channel",
@@ -470,7 +502,7 @@ const flagSets = {
         "browser-additional-instructions"
     ],
     run: [
-        ...commonFlags, "task", "input", "template", "external-run-id", "email-address",
+        ...commonFlags, "task", "input", "template", "model", "external-run-id", "email-address",
         "supabase-user-id",
         "telegram-bot-token", "telegram-allowed-user",
         "dry-run", "wait", "watch", "jsonl", "view", "after-event-id", "stop-on-interrupt",
@@ -534,7 +566,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", "mode", "llm-budget-usd",
+    "model-provider", "model", "harness", "mode", "allowed-model", "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"
@@ -726,8 +758,7 @@ 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.");
+    const modelId = flags.model === undefined ? undefined : flagString(flags, "model").trim();
     if (hasFlag(flags, "wait") && wantsWatch(flags)) {
         throw new Error("--wait cannot be combined with --watch or --jsonl.");
     }
@@ -771,7 +802,8 @@ const commandRun = async (command, flags) => {
     try {
         payload = await createRun(client, {
             cwd: cwd(),
-            instruction: task,
+            instruction: task || undefined,
+            modelId,
             inputs: flagList(flags, "input"),
             externalRunId: flagString(flags, "external-run-id") || undefined,
             supabaseUserId: supabaseUserId || undefined,
@@ -782,7 +814,7 @@ const commandRun = async (command, flags) => {
         });
     }
     catch (error) {
-        throw runCreationError(error, client, template);
+        throw runCreationError(error, client, template, modelId);
     }
     if (wantsWatch(flags)) {
         const watched = await watchRunWithOutput(client, payload.run.id, flags, payload);
@@ -971,7 +1003,7 @@ const commandModelProviders = async (command, flags) => {
         for (const model of payload.models) {
             const modelId = String(model.model_id || model.id || "");
             const displayName = String(model.display_name || model.name || "");
-            process.stdout.write(`${modelId}${displayName && displayName !== modelId ? `\t${displayName}` : ""}${model.selectable === undefined ? "" : `\tselectable=${model.selectable}`}\n`);
+            process.stdout.write(`${modelId}${displayName && displayName !== modelId ? `\t${displayName}` : ""}\n`);
         }
         return;
     }
@@ -1183,6 +1215,13 @@ const commandTemplates = async (command, flags) => {
         if (harness !== "opencode" && modeFlag) {
             throw new CliError("opencode_mode_not_supported", "templates create --mode requires --harness opencode.");
         }
+        const additionalAllowedModels = [...new Set(flagList(flags, "allowed-model").map((value) => value.trim()).filter(Boolean))];
+        if (additionalAllowedModels.length > 0 && (harness !== "opencode" || mode !== "computer")) {
+            throw new CliError("opencode_allowed_models_not_supported", "templates create --allowed-model requires an OpenCode Computer template.");
+        }
+        const allowedModelIds = additionalAllowedModels.length > 0
+            ? [...new Set([model, ...additionalAllowedModels])]
+            : undefined;
         const budgetRaw = flagString(flags, "llm-budget-usd");
         const parsedBudgetUsd = budgetRaw ? Number(budgetRaw) : undefined;
         const llmBudgetUsd = parsedBudgetUsd === undefined
@@ -1198,6 +1237,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.");
@@ -1218,8 +1260,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"))
@@ -1236,6 +1279,7 @@ const commandTemplates = async (command, flags) => {
                 name,
                 provider_id: modelProvider,
                 model_id: model,
+                ...(allowedModelIds ? { allowed_model_ids: allowedModelIds } : {}),
                 ...(harness === "opencode" && modeFlag ? { mode: mode } : {}),
                 ...(llmBudgetUsd === undefined ? {} : { llm_budget_usd: llmBudgetUsd }),
                 ...(harness === "browser-use" ? {

package/dist/runs.js

@@ -52,7 +52,8 @@ export const createRun = async (client, options) => {
     return client.createRun({
         external_run_id: options.externalRunId,
         workload_id: options.templateId,
-        instruction: options.instruction,
+        ...(options.modelId !== undefined ? { model_id: options.modelId } : {}),
+        ...(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.12";
+export const version = "0.0.14";

package/package.json

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