@sanlabs/sanbox-cli 0.0.14 → 0.0.16

package/README.md

@@ -1,10 +1,12 @@
 # Sanbox CLI
 
+Fetch the LLM guide with `sanbox skill` through `/v1/skill`, which validates `SANBOX_API_KEY` from the agent environment. `/agent.md` remains public for older clients and direct links; the new CLI does not fall back to that route. `sanbox skill --write` saves the current guide to `.sanbox/agent.md`. `sanbox init agent` remains a deprecated alias; `sanbox init` writes only a bootstrap pointer. Set `SANBOX_API_URL` to your console's API origin for staging or self-hosted installations. Remote origins require HTTPS; development HTTP is limited to literal loopback.
+
 Run isolated Sanbox agent tasks from a terminal, CI job, or autonomous coding agent.
 
 Sanbox packages a task and selected inputs, starts an isolated runner, streams events, and keeps the sandbox and outputs indefinitely.
 
-The full machine operating protocol is available at https://console.sanbox.cloud/agent.md and in [`web/public/agent.md`](../web/public/agent.md).
+The full machine operating protocol is available at https://console.sanbox.cloud/agent.md and in [`app/docs/agent.md`](../app/docs/agent.md).
 
 ## Install
 
@@ -15,7 +17,19 @@ 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.16 adds `sanbox skill` to retrieve the current LLM
+guide from `/v1/skill` using an organization API key in `SANBOX_API_KEY`. It prints Markdown by
+default, supports `--json`, and saves `.sanbox/agent.md` atomically with `--write`.
+`sanbox init agent` is now a deprecated alias that requires the same key; plain `sanbox init`
+writes a bootstrap pointer instead of an embedded guide. The new CLI requires API support for
+`/v1/skill` and does not fall back to the public `/agent.md` compatibility URL.
+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 +402,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,7 @@
 #!/usr/bin/env node
+import { proxyCommand, formatProxyResult, secretProxiesHelp } from "./secretProxies.js";
+import { formatNetworkAccess, grantTemplateProxies, resolveSecretProxies } from "./templateSecretProxies.js";
+import { agentGuideUrl, fetchSkill, writeSkill, skillBootstrap } from "./skill.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { formatActivityJsonl, formatActivityLine, parseActivityView, shouldRenderEvent } from "./activity.js";
@@ -30,6 +33,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 +44,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]
@@ -64,7 +68,8 @@ Commands:
   sanbox opencode connections revoke <run-id> <connection-id> [--json]
   sanbox ssh <run-id>
   sanbox init [--force]
-  sanbox init agent [--write]
+  sanbox skill [--write] [--json]
+  sanbox init agent [--write] (deprecated alias for skill)
 `;
 const sshHelp = `Sanbox SSH
 
@@ -170,10 +175,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.
@@ -188,111 +196,6 @@ Optional controls: --browser-max-steps, --browser-step-timeout-seconds,
 --browser-download-policy allow|deny, and --browser-additional-instructions.
 Deleting a template requires --force. Existing runs and their retained sandboxes are preserved.
 `;
-const agentInstructions = `# Operate Sanbox Autonomously
-
-Use the \`sanbox\` CLI for focused, isolated, long-running, risky, or parallel work. The canonical
-protocol is https://console.sanbox.cloud/agent.md.
-
-Always use the latest published CLI. Install and verify it at the start of every operating session:
-\`\`\`bash
-npm install -g @sanlabs/sanbox-cli@latest
-latest_cli_version="$(npm view @sanlabs/sanbox-cli version)"
-installed_cli_version="$(sanbox --version)"
-test "$installed_cli_version" = "$latest_cli_version"
-\`\`\`
-
-Human bootstrap:
-- A human/admin supplies an organization-scoped SANBOX_API_KEY and configures provider credentials plus a runnable template.
-- Never print, persist, prompt with, or upload API keys or provider credentials.
-- If the key or a runnable template is unavailable, stop with the exact human action required.
-
-Deterministic startup:
-\`\`\`bash
-sanbox --version
-sanbox auth check --json
-sanbox context --json
-sanbox templates list --json
-export SANBOX_TEMPLATE=<returned-template-id-or-slug>
-sanbox templates validate "$SANBOX_TEMPLATE" --json
-sanbox doctor --json
-\`\`\`
-
-Never guess opaque IDs. The CLI derives the organization from the API key and requires the key to
-resolve to exactly one organization. For task execution, select only a template with runnable: true,
-template_type: "runner", and runner_config.harness: "opencode" or "browser-use". Select Browser Use
-only for a one-shot web task whose target domains are already approved on the template. Never select
-a Hermes service template for a waited task because it is always-on. Select automatically only when exactly one task
-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
-waited remote failure, and 130 detached while remote work continues.
-
-Preview and submit each logical task with a stable idempotency key:
-\`\`\`bash
-sanbox run "Investigate one focused task and write output/report.md" --input app/ --dry-run --json
-sanbox run "Investigate one focused task and write output/report.md" \\
-  --template "$SANBOX_TEMPLATE" --external-run-id "<stable-project-task-id>" \\
-  --input app/ --wait --json
-\`\`\`
-
-Reuse the same --external-run-id after ambiguous failures. Retry network errors, HTTP 429, HTTP 5xx,
-and workspace_busy with bounded backoff. Do not retry other 4xx errors unless next_actions directs
-recovery. A run is inactive when state is stopped; inspect latest_execution.outcome for the most
-recent bounded execution outcome.
-
-Recover and retrieve results:
-\`\`\`bash
-sanbox runs list --limit 50 --json
-sanbox runs get <run-id> --json
-sanbox runs events <run-id> --after-event-id <cursor> --json
-sanbox runs watch <run-id> --after-event-id <cursor> --jsonl
-sanbox runs artifacts <run-id> --json
-sanbox runs download <run-id> --output .sanbox/output/<run-id> --json
-\`\`\`
-
-Tasks must put durable files under /workspace/output. Downloads preserve relative paths and report
-byte counts plus SHA-256 digests; existing files require explicit --overwrite.
-
-While a sandbox is running, create one read-only capability URL for its entire root filesystem:
-\`\`\`bash
-sanbox runs share <run-id> --expires 1h --json
-sanbox runs shares <run-id> --json
-sanbox runs unshare <run-id> <access-point-id> --json
-\`\`\`
-The URL starts at /, supports directory JSON with ?format=json, and stops working when the sandbox
-stops, the link expires, or it is revoked. Treat the URL as a bearer secret.
-
-Manage the retained sandbox independently of its agent harness:
-\`\`\`bash
-sanbox runs get <run-id> --json
-sanbox runs resume <run-id> --wait --json
-sanbox runs share <run-id> --expires 1h --json
-sanbox runs stop <run-id> --wait --json
-sanbox runs delete <run-id> --yes --json
-\`\`\`
-
-Stop terminates compute and durably syncs the workspace without retaining RAM or VM state. Resume
-fresh-boots the pinned runtime artifact with that workspace; it does not restore process state or
-silently replay a finished task. Delete permanently removes the workspace after archiving usage.
-
-For independent fan-out, use \`sanbox batch\` with a stable external_run_id per task and keep the
-client alive until submission completes.
-
-Do not claim completion until state is stopped, latest_execution.outcome is completed, and required
-artifacts are downloaded and verified. Report run/external/template IDs, run state, execution outcome, workspace save time,
-artifact paths/digests, and blockers. The CLI excludes common secrets by default; add
-.sanboxignore for project rules.
-`;
 const cwd = () => process.cwd();
 const makeClient = (flags) => new SanboxClient(readConfig(flags));
 const jsonContext = (client) => ({
@@ -468,6 +371,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 +395,8 @@ const flagSets = {
     "templates.delete": [...commonFlags, "force"],
     "templates.create": [
         ...commonFlags,
+        "secret-proxy",
+        "add-network-access",
         "name",
         "model-provider",
         "model",
@@ -536,6 +449,7 @@ const flagSets = {
     logout: ["api-url", "json", "help"],
     init: [...commonFlags, "force", "template"],
     "init.agent": [...commonFlags, "write"],
+    skill: ["api-url", "json", "help", "write"],
     version: ["json", "help"]
 };
 const commandKey = (command) => {
@@ -549,7 +463,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 +476,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 +524,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,7 +539,11 @@ 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,
+        skill: 1,
         context: 1,
         doctor: 1,
         "model-providers.list": 2,
@@ -1273,6 +1194,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 +1233,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 +1269,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") {
@@ -1782,33 +1725,31 @@ const commandLogout = async (flags) => {
         process.stdout.write(session ? "Signed out.\n" : "No saved Sanbox user session.\n");
     }
 };
+const commandSkill = async (flags, command = "skill") => {
+    const guide = await fetchSkill(resolveApiUrl(flags));
+    if (hasFlag(flags, "write")) {
+        await writeSkill(cwd(), guide);
+        if (hasFlag(flags, "json"))
+            printSuccess(command, { path: ".sanbox/agent.md", status: "written" }, localJsonContext(flags));
+        else
+            process.stdout.write(".sanbox/agent.md written\n");
+    }
+    else if (hasFlag(flags, "json")) {
+        printSuccess(command, { instructions: guide }, localJsonContext(flags));
+    }
+    else
+        process.stdout.write(guide);
+};
 const commandInit = async (command, flags) => {
     const dir = path.join(cwd(), ".sanbox");
-    if (command[1] === "agent") {
-        if (hasFlag(flags, "write")) {
-            await fs.mkdir(dir, { recursive: true });
-            await fs.writeFile(path.join(dir, "agent.md"), agentInstructions, "utf8");
-            if (hasFlag(flags, "json")) {
-                printSuccess("init.agent", { path: ".sanbox/agent.md", status: "written" }, localJsonContext(flags));
-            }
-            else {
-                process.stdout.write(".sanbox/agent.md written\n");
-            }
-            return;
-        }
-        if (hasFlag(flags, "json")) {
-            printSuccess("init.agent", { instructions: agentInstructions }, localJsonContext(flags));
-        }
-        else {
-            process.stdout.write(agentInstructions);
-        }
-        return;
-    }
+    if (command[1] === "agent")
+        return commandSkill(flags, "init.agent");
     if (command[1])
         throw new Error("init supports no subcommand or `agent`.");
     const force = hasFlag(flags, "force");
     const localConfig = readLocalConfig();
     const apiUrl = String(flags["api-url"] || process.env.SANBOX_API_URL || localConfig.api_url || defaultApiUrl).replace(/\/+$/, "");
+    const bootstrap = skillBootstrap(apiUrl);
     const template = readTemplateSelection(flags, { required: false });
     const config = {
         api_url: apiUrl,
@@ -1825,7 +1766,7 @@ const commandInit = async (command, flags) => {
     await fs.mkdir(dir, { recursive: true });
     const results = [
         [".sanbox/config.json", await writeIfNeeded(path.join(dir, "config.json"), `${JSON.stringify(config, null, 2)}\n`, force)],
-        [".sanbox/agent.md", await writeIfNeeded(path.join(dir, "agent.md"), agentInstructions, force)],
+        [".sanbox/agent.md", await writeIfNeeded(path.join(dir, "agent.md"), bootstrap, force)],
         [".sanboxignore", await writeIfNeeded(path.join(cwd(), ".sanboxignore"), sanboxIgnore, force)]
     ];
     if (hasFlag(flags, "json")) {
@@ -1846,6 +1787,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 +1863,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") {
@@ -1943,17 +1895,29 @@ const main = async (command, flags) => {
             process.exitCode = exitCode;
         return;
     }
+    if (command[0] === "skill")
+        return commandSkill(flags);
     if (command[0] === "init")
         return commandInit(command, flags);
     throw new CliError("unknown_command", `Unknown command: ${command.join(" ")}`);
 };
 const parsed = parseArgs(process.argv.slice(2));
 main(parsed.command, parsed.flags).catch((error) => {
+    let context = localJsonContext(parsed.flags);
+    if (parsed.command[0] === "skill" || parsed.command[0] === "init") {
+        // Rejected origins may contain a password/query secret; never echo them.
+        try {
+            context = { api_url: agentGuideUrl(resolveApiUrl(parsed.flags)).origin };
+        }
+        catch {
+            context = {};
+        }
+    }
     if (hasFlag(parsed.flags, "jsonl")) {
-        printJsonlError(commandId(parsed.command), error, localJsonContext(parsed.flags));
+        printJsonlError(commandId(parsed.command), error, context);
     }
     else if (hasFlag(parsed.flags, "json")) {
-        printError(commandId(parsed.command), error, localJsonContext(parsed.flags));
+        printError(commandId(parsed.command), error, context);
     }
     else {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);

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

@@ -0,0 +1,82 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { CliError } from "./errors.js";
+export function agentGuideUrl(apiUrl) {
+    try {
+        const url = new URL(apiUrl);
+        const loopback = url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+        if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+            url.username || url.password || url.search || url.hash || !/^\/*$/.test(url.pathname))
+            throw new Error();
+        return new URL("/v1/skill", url);
+    }
+    catch {
+        throw new CliError("invalid_api_url", "Use an HTTPS API origin, or HTTP on literal loopback for local development.");
+    }
+}
+export async function fetchSkill(apiUrl) {
+    const url = agentGuideUrl(apiUrl);
+    const apiKey = process.env.SANBOX_API_KEY;
+    if (!apiKey?.startsWith("sbx_live_")) {
+        throw new CliError("api_key_required", "Set SANBOX_API_KEY to an organization API key in your agent environment, then run sanbox skill.");
+    }
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: { Authorization: `Bearer ${apiKey}`, Accept: "text/markdown" },
+            redirect: "error",
+            signal: AbortSignal.timeout(15_000)
+        });
+    }
+    catch {
+        throw new CliError("skill_fetch_failed", "Could not fetch the guide. Check SANBOX_API_URL and connectivity. Redirects are not followed.");
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        // Do not echo an untrusted response body or credential-bearing URL.
+        throw new CliError("skill_fetch_failed", response.status === 401 || response.status === 403
+            ? "The guide requires an active organization API key. Check SANBOX_API_KEY."
+            : `The guide could not be fetched (HTTP ${response.status}).`, { status: response.status });
+    }
+    if (response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() !== "text/markdown") {
+        await response.body?.cancel();
+        throw new CliError("invalid_skill_response", "The API did not return a Markdown guide.");
+    }
+    try {
+        const reader = response.body.getReader();
+        const chunks = [];
+        let size = 0;
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.length;
+            if (size > 1_048_576) {
+                await reader.cancel();
+                throw new Error();
+            }
+            chunks.push(value);
+        }
+        const guide = Buffer.concat(chunks).toString("utf8");
+        if (!guide.trim())
+            throw new Error();
+        return guide;
+    }
+    catch {
+        throw new CliError("invalid_skill_response", "The guide was empty, incomplete, or exceeded 1 MiB. Try again.");
+    }
+}
+export async function writeSkill(cwd, guide) {
+    const directory = path.join(cwd, ".sanbox");
+    await fs.mkdir(directory, { recursive: true });
+    const temporary = path.join(directory, `.agent-${randomUUID()}.tmp`);
+    try {
+        await fs.writeFile(temporary, guide, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        await fs.rename(temporary, path.join(directory, "agent.md"));
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+}
+export const skillBootstrap = (apiUrl) => `# Sanbox skill\n\nSet SANBOX_API_KEY in your agent environment or secret settings. Never put the key in chat or tracked files.\n\nUse SANBOX_API_URL=${agentGuideUrl(apiUrl).origin} and run \`sanbox skill\` to read the guide through the authenticated API, or \`sanbox skill --write\` to replace this file.\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.16";

package/package.json

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