@sanlabs/sanbox-cli 0.0.4 → 0.0.9

package/README.md

@@ -2,31 +2,73 @@
 
 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).
 
 ## Install
 
 ```bash
 npm install -g @sanlabs/sanbox-cli@latest
-sanbox --version
+latest_cli_version="$(npm view @sanlabs/sanbox-cli version)"
+installed_cli_version="$(sanbox --version)"
+test "$installed_cli_version" = "$latest_cli_version"
 ```
 
-CLI 0.0.4 adds strict argument validation, stable JSON envelopes, existing-resource discovery, resumable watches, verified artifact downloads, and correlated post-run follow-ups.
+Always use the latest published CLI. CLI 0.0.9 adds user login for private SSH access to running
+Hermes Computers.
+CLI 0.0.6 added Anthropic self-hosted environment inspection and administration.
 
 ## Configure
 
+For an interactive local terminal, sign in with your Sanbox account:
+
+```bash
+sanbox login
+```
+
+The CLI opens the console for approval, binds the session to one organization, and stores it in
+`~/.sanbox/credentials.json`. The file is written atomically and limited to the current user on
+POSIX systems. Run `sanbox logout` to revoke and remove that session.
+
+For non-interactive automation, continue to use an organization API key:
+
 ```bash
 export SANBOX_API_URL=https://console.sanbox.cloud
 export SANBOX_API_KEY=sbx_live_...
-sanbox orgs list --json
-export SANBOX_ORG=<returned-org-slug>
 export SANBOX_TEMPLATE=<template-id-or-slug>
 ```
 
-`SANBOX_API_URL` is optional for the hosted service. `SANBOX_TEMPLATE` can instead come from `--template` or `.sanbox/config.json` `default_template`.
+`SANBOX_API_URL` is optional for the hosted service. `SANBOX_TEMPLATE` can instead come from
+`--template` or `.sanbox/config.json` `default_template`. Organization API keys are for automation;
+they cannot open terminal or SSH sessions.
 
 An org admin configures provider credentials and templates in the console. Do not pass provider keys to the CLI or a runner.
 
+## Connect An Anthropic Self-Hosted Environment
+
+Create a `self_hosted` environment in Claude Console and generate its environment key. Then connect
+it to Sanbox:
+
+```bash
+export ANTHROPIC_ENVIRONMENT_KEY='<environment-key>'
+sanbox anthropic-environments connect env_example --json
+unset ANTHROPIC_ENVIRONMENT_KEY
+
+sanbox anthropic-environments get env_example --json
+sanbox anthropic-environments list --json
+```
+
+The environment key is read only from `ANTHROPIC_ENVIRONMENT_KEY`; there is no secret-bearing CLI
+flag. Connect, key replacement, and disconnect require an organization-admin user session or
+operator credential. Regular organization-scoped member keys can list and inspect connections.
+
+Disconnecting requires explicit confirmation and preserves existing session-to-workspace mappings:
+
+```bash
+sanbox anthropic-environments disconnect env_example --force --json
+```
+
 ## Check Readiness
 
 ```bash
@@ -37,7 +79,34 @@ sanbox templates validate "$SANBOX_TEMPLATE" --json
 sanbox doctor --json
 ```
 
-Model IDs are provider-scoped. The CLI never guesses or silently substitutes an organization, provider, model, or template.
+Model IDs are provider-scoped. The CLI never guesses or silently substitutes a provider, model, or template.
+For waited task runs, choose a template with `runnable: true`, `template_type: "runner"`, and
+`runner_config.harness: "opencode"` or `"browser-use"`. Browser Use is for one-shot web tasks whose
+target domains are already approved. Hermes service templates are always-on.
+
+## Create A Browser Use Template
+
+Browser Use runs local headless Chromium inside the Firecracker sandbox. It requires OpenAI,
+Anthropic, or Google Gemini and at least one explicit browser target:
+
+```bash
+sanbox templates create \
+  --name "Web research" \
+  --harness browser-use \
+  --model-provider openai \
+  --model '<model-id>' \
+  --browser-domain example.com \
+  --browser-domain '*.example.org' \
+  --browser-max-steps 30 \
+  --browser-step-timeout-seconds 120 \
+  --browser-vision-mode auto \
+  --browser-viewport 1280x720 \
+  --browser-download-policy allow
+```
+
+Targets are limited to hostnames and leading wildcards on ports 80 and 443. The remaining browser
+security controls are fixed. Runs return `browser-use-response.md`, a sanitized run ledger, and any
+allowed downloads. Browser Use templates do not support retained follow-up messages.
 
 ## Run Idempotently
 
@@ -84,14 +153,66 @@ sanbox runs download <run-id> \
 
 Downloads are path-safe and return their byte counts and SHA-256 digests. Existing files are preserved unless `--overwrite` is explicit.
 
-## Continue A Run
+## Share A Running Filesystem
+
+Create one read-only bearer URL for the running sandbox's 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 always starts at `/`; there is no root or output selector. Append a path to read an arbitrary
+ordinary file, or add `?format=json` to a directory URL for agent-friendly navigation. The URL stops
+working when the exact sandbox session stops, the link expires, or it is revoked. It is shown only
+when created and must be handled as a bearer secret. See
+[Live Filesystem Access](../docs/live-filesystem-access.md) for the HTTP contract and exclusions.
+
+## Resume Or Pause A Sandbox
+
+```bash
+sanbox runs get <run-id> --json
+sanbox runs resume <run-id> --wait --json
+sanbox runs share <run-id> --expires 1h --json
+sanbox runs pause <run-id> --wait --json
+```
+
+Resume restores the latest writable Firecracker snapshot without starting the configured agent
+harness. It acquires an exclusive manual lease and leaves the sandbox running for live filesystem
+access until Pause creates the next snapshot generation. Do not submit agent work while that lease is
+active. Paused state has no retention TTL and remains available until explicitly deleted.
+
+## SSH Into A Hermes Computer
+
+```bash
+sanbox login
+sanbox ssh <run-id>
+```
+
+The run must be a currently running Hermes Computer created from the SSH-capable template artifact.
+The signed-in user must own the run or be an organization admin. The command uses your local OpenSSH
+client, but it does not expose the microVM on a public IP or port. The CLI generates a temporary
+Ed25519 identity, pins the microVM's runtime host key, and tunnels the SSH stream over a one-time
+authenticated WebSocket. The temporary key is deleted when the connection closes, and the saved
+user token is not passed to the OpenSSH child process.
+
+## Continue An OpenCode Run
 
 ```bash
 sanbox runs messages <run-id> --json
 sanbox runs message <run-id> "Summarize the retained output" --wait --json
 ```
 
-The JSON response includes the user `message`, submitted `chat_job`, matching terminal `followup_event`, and conversation messages. The waiter matches `payload.chat_job_id`, so another concurrent follow-up cannot complete the wrong command.
+The JSON response includes the user `message`, submitted `chat_job`, matching terminal
+`followup_event`, and conversation messages. The waiter matches `payload.chat_job_id`, so another
+concurrent follow-up cannot complete the wrong command. The follow-up resumes OpenCode for one turn,
+then pauses the sandbox again.
+
+Check `sanbox runs get <run-id> --json` before a follow-up and require `sandbox_state: "paused"` with
+a positive `snapshot_generation`. Do not submit concurrent follow-ups to one run.
+Treat `browser_use_followup_unsupported` as a signal to create a new browser agent run; its persisted
+sandbox can still be resumed manually when a snapshot exists.
 
 ## Batch Work
 

package/dist/api.js

@@ -1,3 +1,4 @@
+import { CliError } from "./errors.js";
 const errorRecord = (body) => {
     if (!body || typeof body !== "object" || Array.isArray(body))
         return null;
@@ -38,6 +39,9 @@ export class SanboxApiError extends Error {
 }
 export class SanboxClient {
     config;
+    mePromise = null;
+    organizationPromise = null;
+    organizationSlug = null;
     constructor(config) {
         this.config = config;
     }
@@ -80,22 +84,50 @@ export class SanboxClient {
         return res;
     }
     me() {
-        return this.request("/v1/me");
+        this.mePromise ||= this.request("/v1/me");
+        return this.mePromise;
+    }
+    organization() {
+        this.organizationPromise ||= this.resolveOrganization();
+        return this.organizationPromise;
+    }
+    resolvedOrganizationSlug() {
+        return this.organizationSlug;
+    }
+    async resolveOrganization() {
+        const me = await this.me();
+        const organizations = Array.isArray(me.organizations)
+            ? me.organizations.filter((item) => Boolean(item)
+                && typeof item === "object"
+                && !Array.isArray(item)
+                && typeof item.id === "string"
+                && typeof item.slug === "string"
+                && Boolean(String(item.slug).trim()))
+            : [];
+        if (organizations.length === 0) {
+            throw new CliError("organization_not_found", "The API key is not associated with an organization.");
+        }
+        if (organizations.length > 1) {
+            throw new CliError("organization_ambiguous", "The API key can access multiple organizations. Use an organization-scoped API key.");
+        }
+        this.organizationSlug = organizations[0].slug;
+        return organizations[0];
     }
-    listOrganizations() {
-        return this.request("/v1/orgs");
+    async orgPath(path) {
+        const organization = await this.organization();
+        return `/v1/orgs/${encodeURIComponent(organization.slug)}${path}`;
     }
-    listRuns(limit = 50) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs?limit=${limit}`);
+    async listRuns(limit = 50) {
+        return this.request(`${await this.orgPath("/runs")}?limit=${limit}`);
     }
-    createRun(body) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs`, {
+    async createRun(body) {
+        return this.request(await this.orgPath("/runs"), {
             method: "POST",
             body: JSON.stringify(body)
         });
     }
-    uploadInputCollection(input) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/input-collections`, {
+    async uploadInputCollection(input) {
+        return this.request(await this.orgPath("/input-collections"), {
             method: "POST",
             headers: {
                 "Content-Type": "application/vnd.sanbox.input+zip",
@@ -105,8 +137,8 @@ export class SanboxClient {
             body: Uint8Array.from(input.buffer).buffer
         });
     }
-    listModelProviders() {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/model-providers`);
+    async listModelProviders() {
+        return this.request(await this.orgPath("/model-providers"));
     }
     async getModelProvider(providerId) {
         const payload = await this.listModelProviders();
@@ -115,49 +147,94 @@ export class SanboxClient {
             throw new SanboxApiError(`Model provider ${providerId} was not found.`, 404, { code: "model_provider_not_found" });
         return { provider };
     }
-    listProviderModels(providerId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/model-providers/${encodeURIComponent(providerId)}/models`);
+    async listProviderModels(providerId) {
+        return this.request(await this.orgPath(`/model-providers/${encodeURIComponent(providerId)}/models`));
+    }
+    async listAnthropicEnvironments() {
+        return this.request(await this.orgPath("/anthropic-environments"));
+    }
+    async getAnthropicEnvironment(environmentId) {
+        return this.request(await this.orgPath(`/anthropic-environments/${encodeURIComponent(environmentId)}`));
+    }
+    async connectAnthropicEnvironment(environmentId, environmentKey) {
+        return this.request(await this.orgPath(`/anthropic-environments/${encodeURIComponent(environmentId)}`), {
+            method: "PUT",
+            body: JSON.stringify({ environment_key: environmentKey })
+        });
+    }
+    async disconnectAnthropicEnvironment(environmentId) {
+        return this.request(await this.orgPath(`/anthropic-environments/${encodeURIComponent(environmentId)}`), { method: "DELETE" });
     }
-    listTemplates() {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates`);
+    async listTemplates() {
+        return this.request(await this.orgPath("/templates"));
     }
-    getTemplate(templateId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates/${encodeURIComponent(templateId)}`);
+    async getTemplate(templateId) {
+        return this.request(await this.orgPath(`/templates/${encodeURIComponent(templateId)}`));
     }
-    validateTemplate(templateId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates/${encodeURIComponent(templateId)}/validate`);
+    async validateTemplate(templateId) {
+        return this.request(await this.orgPath(`/templates/${encodeURIComponent(templateId)}/validate`));
     }
-    createTemplate(body) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates`, {
+    async createTemplate(body) {
+        return this.request(await this.orgPath("/templates"), {
             method: "POST",
             body: JSON.stringify(body)
         });
     }
-    getRun(runId, signal) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}`, { signal });
+    async getRun(runId, signal) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}`), { signal });
+    }
+    async createSSHSession(runId, publicKey) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/ssh-sessions`), {
+            method: "POST",
+            body: JSON.stringify({ public_key: publicKey })
+        });
     }
-    listEvents(runId, afterEventId = 0, limit = 200, signal) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/events?after_event_id=${afterEventId}&limit=${limit}`, { signal });
+    async listEvents(runId, afterEventId = 0, limit = 200, signal) {
+        return this.request(`${await this.orgPath(`/runs/${encodeURIComponent(runId)}/events`)}?after_event_id=${afterEventId}&limit=${limit}`, { signal });
     }
-    cancelRun(runId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/cancel`, {
+    async cancelRun(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/cancel`), {
             method: "POST",
             body: "{}"
         });
     }
-    sendMessage(runId, message, payload = {}) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/messages`, {
+    async resumeRun(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/resume`), {
+            method: "POST",
+            body: "{}"
+        });
+    }
+    async pauseRun(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/pause`), {
+            method: "POST",
+            body: "{}"
+        });
+    }
+    async sendMessage(runId, message, payload = {}) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/messages`), {
             method: "POST",
             body: JSON.stringify({ message, payload })
         });
     }
-    listMessages(runId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/messages`);
+    async listMessages(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/messages`));
+    }
+    async listArtifacts(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/artifacts`));
+    }
+    async listFileAccessPoints(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/file-access-points`));
+    }
+    async createFileAccessPoint(runId, input) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/file-access-points`), {
+            method: "POST",
+            body: JSON.stringify(input)
+        });
     }
-    listArtifacts(runId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/artifacts`);
+    async revokeFileAccessPoint(runId, accessPointId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/file-access-points/${encodeURIComponent(accessPointId)}`), { method: "DELETE" });
     }
-    downloadArtifact(runId, artifactPath) {
-        return this.rawRequest(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/artifacts?path=${encodeURIComponent(artifactPath)}`);
+    async downloadArtifact(runId, artifactPath) {
+        return this.rawRequest(`${await this.orgPath(`/runs/${encodeURIComponent(runId)}/artifacts`)}?path=${encodeURIComponent(artifactPath)}`);
     }
 }

package/dist/args.js

@@ -1,4 +1,10 @@
-const multiFlags = new Set(["input", "include", "artifact"]);
+const multiFlags = new Set([
+    "input",
+    "include",
+    "artifact",
+    "telegram-allowed-user",
+    "browser-domain"
+]);
 export const booleanFlags = new Set([
     "help",
     "version",
@@ -12,7 +18,8 @@ export const booleanFlags = new Set([
     "verbose",
     "force",
     "write",
-    "overwrite"
+    "overwrite",
+    "no-browser"
 ]);
 export const parseArgs = (argv) => {
     const command = [];