@sanlabs/sanbox-cli 0.0.15 → 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,13 @@ installed_cli_version="$(sanbox --version)"
 test "$installed_cli_version" = "$latest_cli_version"
 ```
 
-Always use the latest published CLI. CLI 0.0.15 adds Secret Proxy management, template grants,
+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

package/dist/cli.js

@@ -1,6 +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";
@@ -67,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
 
@@ -194,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) => ({
@@ -552,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) => {
@@ -645,6 +543,7 @@ const validatePositionals = (command, flags) => {
         "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,
@@ -1826,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,
@@ -1869,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")) {
@@ -1998,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/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/version.js

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

package/package.json

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