@sanlabs/sanbox-cli 0.0.13 → 0.0.14

package/README.md

@@ -15,7 +15,11 @@ installed_cli_version="$(sanbox --version)"
 test "$installed_cli_version" = "$latest_cli_version"
 ```
 
-Always use the latest published CLI. CLI 0.0.13 allows service templates to start without an
+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,
@@ -99,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:

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,11 +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 --template <service-template-id> [--email-address <address>] [--telegram-bot-token <token>] [--telegram-allowed-user <id>] [--json]
+  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]
@@ -95,11 +95,14 @@ 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.
@@ -113,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
 
@@ -163,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
@@ -216,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
@@ -316,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 = [
@@ -348,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") {
@@ -461,6 +489,7 @@ const flagSets = {
         "model",
         "harness",
         "mode",
+        "allowed-model",
         "llm-budget-usd",
         "web-access",
         "channel",
@@ -473,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",
@@ -537,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"
@@ -729,6 +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);
+    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.");
     }
@@ -773,6 +803,7 @@ const commandRun = async (command, flags) => {
         payload = await createRun(client, {
             cwd: cwd(),
             instruction: task || undefined,
+            modelId,
             inputs: flagList(flags, "input"),
             externalRunId: flagString(flags, "external-run-id") || undefined,
             supabaseUserId: supabaseUserId || undefined,
@@ -783,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);
@@ -972,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;
     }
@@ -1184,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
@@ -1241,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,6 +52,7 @@ export const createRun = async (client, options) => {
     return client.createRun({
         external_run_id: options.externalRunId,
         workload_id: options.templateId,
+        ...(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 } : {}),

package/dist/version.js

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

package/package.json

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