@sanlabs/sanbox-cli 0.0.14 → 0.0.15

package/README.md

@@ -15,7 +15,13 @@ installed_cli_version="$(sanbox --version)"
 test "$installed_cli_version" = "$latest_cli_version"
 ```
 
-Always use the latest published CLI. CLI 0.0.14 adds repeatable `--allowed-model` options when
+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.
@@ -388,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,4 +1,6 @@
 const multiFlags = new Set([
+    "path",
+    "secret-proxy",
     "input",
     "include",
     "artifact",
@@ -8,6 +10,9 @@ const multiFlags = new Set([
     "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,7 +43,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] [--mode task|computer] [--allowed-model <model-id>] [--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> [--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]
@@ -170,10 +173,13 @@ Usage:
   sanbox templates list [--json]
   sanbox templates get <template-id> [--json]
   sanbox templates validate <template-id> [--json]
-  sanbox templates create --name "Code review" --model-provider <provider-id> --model <model-id> [--harness opencode|hermes|browser-use] [--mode task|computer] [--allowed-model <model-id>] [--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.
@@ -468,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"],
@@ -484,6 +498,8 @@ const flagSets = {
     "templates.delete": [...commonFlags, "force"],
     "templates.create": [
         ...commonFlags,
+        "secret-proxy",
+        "add-network-access",
         "name",
         "model-provider",
         "model",
@@ -549,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" ||
@@ -561,6 +578,8 @@ 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",
@@ -607,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);
@@ -622,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,
@@ -1273,6 +1295,13 @@ 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({
@@ -1305,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",
@@ -1328,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") {
@@ -1846,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")
@@ -1920,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/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.14";
+export const version = "0.0.15";

package/package.json

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