@sanlabs/sanbox-cli 0.0.13 → 0.0.15

package/README.md

@@ -15,7 +15,17 @@ 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.15 adds Secret Proxy management, template grants,
+and run-scope inspection. Use `--path` or `--all-paths` to configure request scope and repeatable
+`--secret-proxy` options to select proxies during template creation. Grants check HTTPS access;
+`--add-network-access` explicitly adds missing host rules on port 443. Proxy details include
+run-ID attachment, timestamps, and granted template IDs. If setup fails after template creation,
+the CLI reports the existing template ID and recovery commands. See [Secret Proxies](#secret-proxies).
+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 +109,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:
@@ -362,3 +394,51 @@ Batch fan-out is client-side. Keep the CLI process alive until all tasks are sub
 Use `--json` for request/response commands and `--jsonl` for streams. Envelopes have `schema_version`, `ok`, `command`, `context`, `data` or `error`, and `next_actions`.
 
 Exit codes are `0` for command success, `1` for local/API failure, `2` for readiness or waited remote failure, and `130` for a detached watcher.
+
+## Secret Proxies
+
+Create a proxy from a JSON configuration and read its credential from stdin. For example, save this as `proxy.json`:
+
+```json
+{
+  "name": "customer-api",
+  "host": "api.example.com",
+  "authentication": { "type": "bearer" },
+  "attach_run_id": true
+}
+```
+
+```sh
+sanbox secret-proxies create --file proxy.json --secret-stdin \
+  --path /users --path /projects < token-file
+sanbox secret-proxies get customer-api
+sanbox secret-proxies update customer-api --path /users --if-revision 1
+```
+
+Repeat `--path` to select paths and their subpaths, or use `--all-paths` for the entire API. `/users` includes `/users/42`, but excludes `/users-admin`. `/users/` includes descendants but excludes `/users`. Paths do not support wildcards.
+
+These options replace all request rules and allow every supported HTTP method: GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS. To retain method restrictions, supply `request_rules` in the JSON file without either path option. Creation requires an explicit path option or rules in the file. Updates accept `--file`, path options, or both, and require the current `--if-revision`. Names and hosts are immutable.
+
+Grant a proxy to an existing template:
+
+```sh
+sanbox templates secret-proxies grant TEMPLATE_ID customer-api
+sanbox templates secret-proxies grant TEMPLATE_ID customer-api --add-network-access
+```
+
+Grants check whether the host is allowed on HTTPS port 443. Missing or partial access produces a warning and does not prevent the grant. IP/CIDR rules are reported as DNS-dependent when hostname access cannot be confirmed. `--add-network-access` explicitly adds missing host rules on port 443, preserving existing custom rules and descriptions. Managed provider and harness rules remain server-owned.
+
+Select proxies while creating a template with repeatable `--secret-proxy`:
+
+```sh
+sanbox templates create --name "Customer support" \
+  --model-provider openai --model MODEL_ID \
+  --secret-proxy customer-api --secret-proxy billing-api \
+  --add-network-access
+```
+
+Proxy names and IDs are resolved before creation. Network changes and grants are separate operations after the template is created. If setup fails, the CLI exits with an error, reports the existing template ID, and provides grant commands to finish setup. Successful grants and network changes remain saved. Use those recovery commands instead of creating another template.
+
+`secret-proxies get` shows path scope, run-ID attachment, Created/Updated timestamps, and granted template IDs. With `--json`, grant results include `data.network_access`; template creation includes `data.secret_proxies`. Each network check includes its status, whether a rule was added, and any warning. Incomplete setup reports granted/pending proxy IDs under `error.details` and recovery commands under `next_actions`.
+
+There is no enable or test step. Grants and configuration edits apply on the next start or resume. Inspect run scope with `sanbox runs secret-proxies RUN_ID`. Credentials are never accepted in command-line arguments or JSON configuration. See [Secret Proxies](../docs/secret-proxies.md) for runtime behavior, rotation, and deletion.

package/dist/api.js

@@ -165,6 +165,30 @@ export class SanboxClient {
     async disconnectAnthropicEnvironment(environmentId) {
         return this.request(await this.orgPath(`/anthropic-environments/${encodeURIComponent(environmentId)}`), { method: "DELETE" });
     }
+    async listSecretProxies() {
+        return this.request(await this.orgPath("/secret-proxies"));
+    }
+    async getSecretProxy(id) {
+        return this.request(await this.orgPath(`/secret-proxies/${encodeURIComponent(id)}`));
+    }
+    async createSecretProxy(body) {
+        return this.request(await this.orgPath("/secret-proxies"), { method: "POST", body: JSON.stringify(body) });
+    }
+    async updateSecretProxy(id, body) {
+        return this.request(await this.orgPath(`/secret-proxies/${encodeURIComponent(id)}`), { method: "PATCH", body: JSON.stringify(body) });
+    }
+    async deleteSecretProxy(id) {
+        return this.request(await this.orgPath(`/secret-proxies/${encodeURIComponent(id)}`), { method: "DELETE" });
+    }
+    async getTemplateSecretProxies(template) {
+        return this.request(await this.orgPath(`/templates/${encodeURIComponent(template)}/secret-proxies`));
+    }
+    async grantTemplateSecretProxy(template, id, grant = true) {
+        return this.request(await this.orgPath(`/templates/${encodeURIComponent(template)}/secret-proxies/${encodeURIComponent(id)}`), { method: grant ? "PUT" : "DELETE" });
+    }
+    async getRunSecretProxies(run) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(run)}/secret-proxies`));
+    }
     async listTemplates() {
         return this.request(await this.orgPath("/templates"));
     }
@@ -177,6 +201,9 @@ export class SanboxClient {
     async deleteTemplate(templateId) {
         return this.request(await this.orgPath(`/templates/${encodeURIComponent(templateId)}`), { method: "DELETE" });
     }
+    async updateTemplateNetworkPolicy(templateId, networkPolicy) {
+        return this.request(await this.orgPath(`/templates/${encodeURIComponent(templateId)}/network-policy`), { method: "PATCH", body: JSON.stringify({ network_policy: networkPolicy }) });
+    }
     async createTemplate(body) {
         return this.request(await this.orgPath("/templates"), {
             method: "POST",

package/dist/args.js

@@ -1,12 +1,18 @@
 const multiFlags = new Set([
+    "path",
+    "secret-proxy",
     "input",
     "include",
     "artifact",
     "channel",
+    "allowed-model",
     "telegram-allowed-user",
     "browser-domain"
 ]);
 export const booleanFlags = new Set([
+    "all-paths",
+    "add-network-access",
+    "secret-stdin",
     "help",
     "version",
     "json",

package/dist/cli.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { proxyCommand, formatProxyResult, secretProxiesHelp } from "./secretProxies.js";
+import { formatNetworkAccess, grantTemplateProxies, resolveSecretProxies } from "./templateSecretProxies.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { formatActivityJsonl, formatActivityLine, parseActivityView, shouldRenderEvent } from "./activity.js";
@@ -30,6 +32,7 @@ Commands:
   sanbox auth check [--json]
   sanbox context [--json]
   sanbox doctor [--json]
+  sanbox secret-proxies --help
   sanbox model-providers list [--json]
   sanbox model-providers get <provider-id> [--json]
   sanbox model-providers models <provider-id> [--json]
@@ -40,11 +43,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>] [--secret-proxy <name-or-id>] [--add-network-access] [--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 +98,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 +119,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 +173,18 @@ 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>] [--secret-proxy <name-or-id>] [--add-network-access] [--json]
   sanbox templates delete <template-id> --force [--json]
 
 Template creation requires an exact provider id and that provider's exact model id.
+Use repeatable --secret-proxy <name-or-id> to grant saved proxies to the new template.
+Grants check HTTPS access. Add --add-network-access to explicitly allow their hosts on port 443.
+If setup fails after creation, use the reported template id and grant commands to finish setup.
 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 +231,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 +338,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 +382,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") {
@@ -440,6 +474,14 @@ const positionalText = (command, startIndex) => command.slice(startIndex).join("
 const runTask = (command, flags) => flagString(flags, "task") || positionalText(command, 1);
 const commonFlags = ["api-url", "json", "help"];
 const flagSets = {
+    "secret-proxies.list": commonFlags,
+    "secret-proxies.get": commonFlags,
+    "secret-proxies.create": [...commonFlags, "file", "secret-stdin", "path", "all-paths"],
+    "secret-proxies.update": [...commonFlags, "file", "if-revision", "path", "all-paths"],
+    "secret-proxies.rotate": [...commonFlags, "secret-stdin"],
+    "secret-proxies.delete": [...commonFlags, "yes"],
+    "templates.secret-proxies": [...commonFlags, "add-network-access"],
+    "runs.secret-proxies": commonFlags,
     "auth.check": commonFlags,
     context: [...commonFlags, "template"],
     doctor: [...commonFlags, "template"],
@@ -456,11 +498,14 @@ const flagSets = {
     "templates.delete": [...commonFlags, "force"],
     "templates.create": [
         ...commonFlags,
+        "secret-proxy",
+        "add-network-access",
         "name",
         "model-provider",
         "model",
         "harness",
         "mode",
+        "allowed-model",
         "llm-budget-usd",
         "web-access",
         "channel",
@@ -473,7 +518,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",
@@ -520,7 +565,8 @@ const commandKey = (command) => {
         return "runs.supabase";
     if (command[0] === "opencode" && command[1] === "connections")
         return "opencode.connections";
-    if (command[0] === "model-providers" ||
+    if (command[0] === "secret-proxies" ||
+        command[0] === "model-providers" ||
         command[0] === "anthropic-environments" ||
         command[0] === "templates" ||
         command[0] === "runs" ||
@@ -532,12 +578,14 @@ const commandKey = (command) => {
     return command[0];
 };
 const requiredValueFlags = new Set([
+    "path", "secret-proxy",
+    "file", "if-revision",
     "api-url", "template", "task", "input", "include", "external-run-id", "email-address",
     "supabase-user-id", "return-url",
     "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"
@@ -578,7 +626,7 @@ const validateFlags = (command, flags) => {
         return;
     }
     const knownRoots = new Set([
-        "auth", "context", "doctor", "model-providers", "anthropic-environments", "templates",
+        "secret-proxies", "auth", "context", "doctor", "model-providers", "anthropic-environments", "templates",
         "run", "batch", "runs", "opencode", "ssh", "ssh-proxy", "login", "logout", "init", "version"
     ]);
     const allowed = flagSets[key] ?? (knownRoots.has(command[0] || "") ? commonFlags : null);
@@ -593,6 +641,9 @@ const validatePositionals = (command, flags) => {
     if (hasFlag(flags, "help"))
         return;
     const maximums = {
+        "secret-proxies.list": 2, "secret-proxies.get": 3, "secret-proxies.create": 2,
+        "secret-proxies.update": 3, "secret-proxies.rotate": 3, "secret-proxies.delete": 3,
+        "templates.secret-proxies": 5, "runs.secret-proxies": 3,
         "auth.check": 2,
         context: 1,
         doctor: 1,
@@ -729,6 +780,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 +825,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 +836,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 +1025,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 +1237,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
@@ -1235,12 +1295,20 @@ const commandTemplates = async (command, flags) => {
         if (harness !== "hermes" && channels.length > 0) {
             throw new CliError("hermes_channels_not_supported", "--channel requires --harness hermes.");
         }
+        const proxyNames = flagList(flags, "secret-proxy");
+        const addNetworkAccess = hasFlag(flags, "add-network-access");
+        if (addNetworkAccess && !proxyNames.length) {
+            throw new CliError("secret_proxy_required", "--add-network-access requires at least one --secret-proxy.");
+        }
+        // Resolve every selection before creating anything, including name/id aliases.
+        const selectedProxies = await resolveSecretProxies(client, proxyNames);
         let payload;
         try {
             payload = await client.createTemplate({
                 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" ? {
@@ -1266,8 +1334,21 @@ const commandTemplates = async (command, flags) => {
         catch (error) {
             throw templateCreationError(error, client, modelProvider, model);
         }
+        let proxySetup;
+        if (selectedProxies.length) {
+            try {
+                const { template, ...setup } = await grantTemplateProxies(client, payload.template.id, selectedProxies, addNetworkAccess);
+                payload.template = template;
+                proxySetup = setup;
+            }
+            catch (error) {
+                if (error instanceof CliError)
+                    throw new CliError(error.code, `Template ${payload.template.id} was created. Do not rerun templates create.\n${error.message}`, { ...error.options, details: { ...error.options.details, template_created: true } });
+                throw error;
+            }
+        }
         if (hasFlag(flags, "json")) {
-            printSuccess("templates.create", payload, jsonContext(client), [
+            printSuccess("templates.create", { ...payload, ...(proxySetup ? { secret_proxies: proxySetup } : {}) }, jsonContext(client), [
                 commandAction(["sanbox", "templates", "validate", payload.template.id, "--json"], "Validate the new template before running it."),
                 commandAction([
                     "sanbox",
@@ -1289,6 +1370,8 @@ const commandTemplates = async (command, flags) => {
         }
         process.stdout.write(`created ${payload.template.id} provider=${payload.template.provider_id || modelProvider} model=${payload.template.model_id || model}` +
             `${payload.template.llm_budget_usd ? ` budget=$${payload.template.llm_budget_usd}/run` : ""}\n`);
+        if (proxySetup)
+            process.stdout.write(`Granted proxies: ${selectedProxies.map(proxy => proxy.name).join(", ")}\n${formatNetworkAccess(proxySetup.network_access)}`);
         return;
     }
     if (action === "delete") {
@@ -1807,6 +1890,8 @@ const helpFor = (command) => {
         return runsSupabaseHelp;
     if (command[0] === "doctor")
         return doctorHelp;
+    if (command[0] === "secret-proxies" || command[1] === "secret-proxies")
+        return secretProxiesHelp;
     if (command[0] === "model-providers")
         return modelProvidersHelp;
     if (command[0] === "anthropic-environments")
@@ -1881,6 +1966,15 @@ const main = async (command, flags) => {
         return commandContext(flags);
     if (command[0] === "doctor")
         return commandDoctor(flags);
+    if (command[0] === "secret-proxies" || command[1] === "secret-proxies") {
+        const client = makeClient(flags);
+        const payload = await proxyCommand(client, command, flags);
+        if (hasFlag(flags, "json"))
+            printSuccess(commandKey(command) || "secret-proxies", payload, jsonContext(client));
+        else
+            process.stdout.write(formatProxyResult(payload));
+        return;
+    }
     if (command[0] === "model-providers")
         return commandModelProviders(command, flags);
     if (command[0] === "anthropic-environments") {

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/secretProxies.js

@@ -0,0 +1,168 @@
+import fs from "node:fs/promises";
+import { posix } from "node:path";
+import { CliError } from "./errors.js";
+import { isoUtcTimestamp } from "./output.js";
+import { formatNetworkAccess, grantTemplateProxies, resolveSecretProxies } from "./templateSecretProxies.js";
+export const secretProxiesHelp = `Secret Proxies
+  sanbox secret-proxies list
+  sanbox secret-proxies get <name-or-id>
+  sanbox secret-proxies create --file proxy.json --secret-stdin [--path /users | --all-paths]
+  sanbox secret-proxies update <name-or-id> --if-revision <revision> [--file proxy.json] [--path /users | --all-paths]
+  sanbox secret-proxies rotate <name-or-id> --secret-stdin
+  sanbox secret-proxies delete <name-or-id> --yes
+  sanbox templates secret-proxies list <template>
+  sanbox templates secret-proxies grant <template> <name-or-id> [--add-network-access]
+  sanbox templates secret-proxies revoke <template> <name-or-id>
+  sanbox runs secret-proxies <run>
+
+Use --json for structured output. Credentials are read only from stdin.
+Repeat --path for multiple paths. Each includes its subpaths; path wildcards are not supported.
+--path and --all-paths replace request_rules with all supported HTTP methods.
+Without either option, request_rules in the JSON file retain their method restrictions.
+Updates require --file or a path option, and always require --if-revision.
+Names and hosts cannot be updated. Create a new proxy to change either.
+Saving makes a proxy available to granted templates on their next start/resume.
+Call the original HTTPS URL. Network rules must allow its host; matching requests receive credentials automatically.
+Grants check HTTPS access. --add-network-access explicitly adds missing host rules on port 443.
+`;
+export const proxyMethods = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+export function proxyPathRules(flags) {
+    if (flags.path !== undefined && flags["all-paths"]) {
+        throw new CliError("conflicting_paths", "Use either --path or --all-paths, not both.");
+    }
+    if (flags["all-paths"])
+        return [{ path_prefix: "/", methods: [...proxyMethods] }];
+    if (flags.path === undefined)
+        return undefined;
+    const paths = Array.isArray(flags.path) ? flags.path : [flags.path];
+    if (!paths.length || paths.length > 32)
+        throw new CliError("invalid_paths", "Provide between 1 and 32 paths.");
+    for (const path of paths) {
+        if (typeof path !== "string" || !path.startsWith("/") || /[*%\\?#\s\x00-\x20\x7f]/.test(path) ||
+            path.includes("//") || posix.normalize(path) !== path) {
+            throw new CliError("invalid_path", "Use an absolute path such as /users, without wildcards, encoding, queries, whitespace, or dot segments.");
+        }
+    }
+    return [...new Set(paths)].map(path_prefix => ({ path_prefix, methods: [...proxyMethods] }));
+}
+export async function proxyCommand(client, command, flags) {
+    const required = (value) => {
+        if (!value)
+            throw new CliError("argument_required", secretProxiesHelp);
+        return value;
+    };
+    const resolve = async (value) => {
+        return (await resolveSecretProxies(client, [required(value)]))[0];
+    };
+    const readCredential = async () => {
+        if (!flags["secret-stdin"] || process.stdin.isTTY)
+            throw new CliError("secret_stdin_required", "Pipe the credential into stdin and pass --secret-stdin.");
+        let value = "";
+        for await (const chunk of process.stdin) {
+            value += chunk.toString();
+            if (value.length > 8194)
+                throw new CliError("credential_too_long", "Credential exceeds 8192 characters.");
+        }
+        value = value.replace(/\r?\n$/, "");
+        if (!value)
+            throw new CliError("credential_required", "Credential is empty.");
+        return value;
+    };
+    const readConfig = async () => {
+        if (typeof flags.file !== "string")
+            throw new CliError("file_required", "Pass --file with a JSON configuration path.");
+        const stat = await fs.stat(flags.file);
+        if (stat.size > 64_000)
+            throw new CliError("file_too_large", "Configuration exceeds 64 KB.");
+        let config;
+        try {
+            config = JSON.parse(await fs.readFile(flags.file, "utf8"));
+        }
+        catch {
+            throw new CliError("invalid_proxy_json", "Configuration must contain valid JSON.");
+        }
+        if (!config ||
+            typeof config !== "object" ||
+            Array.isArray(config) ||
+            "credential" in config)
+            throw new CliError("invalid_proxy_config", "Use a configuration object without credentials. Pass credentials through stdin.");
+        return config;
+    };
+    if (command[0] === "runs")
+        return client.getRunSecretProxies(required(command[2]));
+    if (command[0] === "templates") {
+        const action = command[2], template = required(command[3]);
+        if (flags["add-network-access"] && action !== "grant") {
+            throw new CliError("unsupported_flag", "--add-network-access is only supported for grants and template creation.");
+        }
+        if (action === "list")
+            return client.getTemplateSecretProxies(template);
+        const proxy = await resolve(command[4]);
+        if (!["grant", "revoke"].includes(action || ""))
+            throw new CliError("invalid_action", secretProxiesHelp);
+        if (action === "revoke")
+            return client.grantTemplateSecretProxy(template, proxy.id, false);
+        const { template: _template, ...setup } = await grantTemplateProxies(client, template, [proxy], Boolean(flags["add-network-access"]));
+        return { granted: true, ...setup };
+    }
+    const action = command[1];
+    if (action === "list")
+        return client.listSecretProxies();
+    const rules = proxyPathRules(flags);
+    if (action === "create") {
+        const config = await readConfig();
+        if (!rules && config.request_rules === undefined) {
+            throw new CliError("paths_required", "Choose --path or --all-paths, or provide request_rules in the configuration file.");
+        }
+        return client.createSecretProxy({
+            ...config,
+            ...(rules ? { request_rules: rules } : {}),
+            credential: await readCredential(),
+        });
+    }
+    const proxy = await resolve(command[2]);
+    if (action === "get")
+        return client.getSecretProxy(proxy.id);
+    if (action === "delete") {
+        if (!flags.yes)
+            throw new CliError("confirmation_required", "Pass --yes to delete the proxy and revoke its active access.");
+        return client.deleteSecretProxy(proxy.id);
+    }
+    if (action === "rotate")
+        return client.updateSecretProxy(proxy.id, {
+            revision: proxy.revision,
+            credential: await readCredential(),
+        });
+    if (action === "update") {
+        const revision = Number(flags["if-revision"]);
+        if (!Number.isInteger(revision) || revision < 1)
+            throw new CliError("revision_required", "Pass --if-revision with the revision you edited.");
+        return client.updateSecretProxy(proxy.id, {
+            ...(flags.file !== undefined || !rules ? await readConfig() : {}),
+            ...(rules ? { request_rules: rules } : {}),
+            revision,
+        });
+    }
+    throw new CliError("invalid_action", secretProxiesHelp);
+}
+export function formatProxyResult(payload) {
+    if ("proxies" in payload)
+        return payload.proxies.length
+            ? payload.proxies.map(proxy => `${proxy.id}\t${proxy.name}\t${proxy.host}\trevision=${proxy.revision}\tattach_run_id=${proxy.attach_run_id}${proxy.updated_at ? `\tupdated=${isoUtcTimestamp(proxy.updated_at)}` : ""}${proxy.granted === undefined ? "" : `\tgranted=${proxy.granted}`}${proxy.removed ? "\tremoved" : ""}`).join("\n") + "\n"
+            : "No secret proxies.\n";
+    if ("proxy" in payload) {
+        const proxy = payload.proxy;
+        const templateIds = payload.template_ids ?? proxy.template_ids;
+        const rules = proxy.request_rules.map(rule => {
+            const allMethods = proxyMethods.every(method => rule.methods.includes(method));
+            const scope = rule.path_prefix === "/" ? "All paths" : `${rule.path_prefix} and subpaths`;
+            return `  ${scope} (${allMethods ? "all supported methods" : rule.methods.join(", ")})`;
+        }).join("\n");
+        return `${proxy.id} ${proxy.name}\nHost: ${proxy.host}\nRevision: ${proxy.revision}\nAuthentication: ${proxy.authentication.type} (${proxy.authentication.header})\nAttach Sanbox run ID: ${proxy.attach_run_id ? "Yes (X-Sanbox-Run-ID)" : "No"}\nCreated: ${proxy.created_at ? isoUtcTimestamp(proxy.created_at) : "Unavailable"}\nUpdated: ${proxy.updated_at ? isoUtcTimestamp(proxy.updated_at) : "Unavailable"}\nPaths:\n${rules}\n${templateIds === undefined ? "" : `Granted templates: ${templateIds.length ? templateIds.join(", ") : "None"}\n`}`;
+    }
+    if ("deleted" in payload)
+        return "Proxy deleted. Future requests receive no injected credential.\n";
+    return payload.granted
+        ? "Granted for the next start or resume.\n" + formatNetworkAccess(payload.network_access ?? [])
+        : "Grant removed for the next start or resume.\n";
+}

package/dist/templateSecretProxies.js

@@ -0,0 +1,119 @@
+import { isIP } from "node:net";
+import { SanboxApiError } from "./api.js";
+import { CliError, commandAction } from "./errors.js";
+export async function resolveSecretProxies(client, names) {
+    if (!names.length)
+        return [];
+    const { proxies } = await client.listSecretProxies();
+    const selected = names.map(name => {
+        const proxy = proxies.find(item => item.id === name || item.name === name);
+        if (!proxy)
+            throw new CliError("proxy_not_found", `Secret proxy ${name} was not found in this organization.`);
+        return proxy;
+    });
+    return [...new Map(selected.map(proxy => [proxy.id, proxy])).values()];
+}
+// Keep static coverage consistent with the console's hostNetworkAccess helper.
+// IP/CIDR rules require runtime DNS, so they cannot prove hostname coverage here.
+export function hostNetworkAccess(host, rules) {
+    const normalize = (value) => value.trim().toLowerCase().replace(/\.$/, "");
+    const target = normalize(host);
+    const covers = (pattern, candidate) => pattern === candidate || pattern.startsWith("*.") && candidate.endsWith(pattern.slice(1));
+    const destinations = rules
+        .filter(rule => rule.ports.some(range => range.from <= 443 && range.to >= 443))
+        .map(rule => normalize(rule.destination));
+    if (destinations.some(destination => covers(destination, target)) ||
+        destinations.includes("0.0.0.0/0") && destinations.includes("::/0"))
+        return "allowed";
+    const addressRule = (destination) => destination.includes("/") || Boolean(isIP(destination));
+    if (target.startsWith("*.") && destinations.some(destination => !addressRule(destination) && covers(target, destination))) {
+        return "partial";
+    }
+    return destinations.some(addressRule) ? "ip-dependent" : "missing";
+}
+function checkNetworkAccess(template, proxy, added = false) {
+    const effective = template.network_access?.effective_rules;
+    const rules = effective ?? template.default_network_policy?.rules ?? [];
+    const coverage = hostNetworkAccess(proxy.host, rules);
+    const status = !effective && coverage !== "allowed" ? "unknown" : coverage;
+    const messages = {
+        missing: `${proxy.host} is not allowed on HTTPS port 443.`,
+        partial: `Only some subdomains of ${proxy.host} are allowed on HTTPS port 443.`,
+        "ip-dependent": `HTTPS access to ${proxy.host} depends on runtime DNS matching the IP/CIDR rules.`,
+        unknown: `The API did not provide enough network policy information to check HTTPS access to ${proxy.host}.`
+    };
+    return {
+        proxy_id: proxy.id, host: proxy.host, status, added,
+        ...(status === "allowed" ? {} : {
+            warning: `${messages[status]} Review the template's network settings or grant again with --add-network-access.`
+        })
+    };
+}
+export function formatNetworkAccess(checks) {
+    return checks.map(check => check.warning
+        ? `Warning: ${check.warning}\n`
+        : `HTTPS access: ${check.host}:443${check.added ? " (network rule added)" : " (already allowed)"}\n`).join("");
+}
+/** Grants and network edits are separate API operations. Keep successful work recoverable. */
+export async function grantTemplateProxies(client, templateId, proxies, addNetworkAccess) {
+    const granted = [];
+    let checks = [];
+    try {
+        let { template } = await client.getTemplate(templateId);
+        templateId = template.id;
+        checks = proxies.map(proxy => checkNetworkAccess(template, proxy));
+        if (addNetworkAccess && checks.some(check => check.status !== "allowed")) {
+            const policy = template.default_network_policy;
+            if (!policy || policy.default_action !== "deny" || !Array.isArray(policy.rules)) {
+                throw new CliError("network_policy_unavailable", "Cannot add network access without the template's existing custom rules.");
+            }
+            // Send only stored custom rules. Managed provider/harness rules remain server-owned.
+            const rules = policy.rules.map(({ destination, ports, description }) => ({
+                destination, ports, ...(description === undefined ? {} : { description })
+            }));
+            const addedHosts = new Set();
+            for (const check of checks) {
+                if (check.status === "allowed" || hostNetworkAccess(check.host, rules) === "allowed")
+                    continue;
+                rules.push({ destination: check.host, ports: [{ from: 443, to: 443 }] });
+                addedHosts.add(check.host);
+            }
+            if (rules.length > 16) {
+                throw new CliError("network_rule_limit", "Adding proxy hosts would exceed the template's limit of 16 custom network rules.");
+            }
+            ({ template } = await client.updateTemplateNetworkPolicy(templateId, { default_action: "deny", rules }));
+            checks = proxies.map(proxy => checkNetworkAccess(template, proxy, addedHosts.has(proxy.host)));
+        }
+        const failed = [];
+        for (const proxy of proxies) {
+            try {
+                await client.grantTemplateSecretProxy(templateId, proxy.id, true);
+                granted.push(proxy.id);
+            }
+            catch (error) {
+                // Do not echo upstream response bodies, which may contain sensitive context.
+                failed.push(`${proxy.name}${error instanceof SanboxApiError ? ` (HTTP ${error.status}, ${error.code})` : ""}`);
+            }
+        }
+        if (failed.length)
+            throw new CliError("proxy_grant_failed", `Could not save access for: ${failed.join(", ")}.`);
+        return { template, template_id: templateId, granted_proxy_ids: granted, network_access: checks };
+    }
+    catch (error) {
+        const pending = proxies.filter(proxy => !granted.includes(proxy.id));
+        const reason = error instanceof CliError ? ` ${error.message}`
+            : error instanceof SanboxApiError ? ` API request failed (HTTP ${error.status}, ${error.code}).` : "";
+        const nextActions = pending.map(proxy => commandAction(["sanbox", "templates", "secret-proxies", "grant", templateId, proxy.id,
+            ...(addNetworkAccess ? ["--add-network-access"] : []), "--api-url", client.config.apiUrl, "--json"], `Finish setting up ${proxy.name} on the existing template.`));
+        const commands = nextActions.map(action => action.type === "command" ? `  ${action.argv.join(" ")}` : "").join("\n");
+        throw new CliError("proxy_setup_incomplete", `Secret Proxy setup is incomplete for template ${templateId}.${reason}\nRetry on this template:\n${commands}`, {
+            details: {
+                template_id: templateId,
+                granted_proxy_ids: granted,
+                pending_proxy_ids: pending.map(proxy => proxy.id),
+                network_access: checks
+            },
+            nextActions
+        });
+    }
+}

package/dist/version.js

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

package/package.json

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