@sanlabs/sanbox-cli 0.0.5 → 0.0.10

package/README.md

@@ -15,23 +15,61 @@ installed_cli_version="$(sanbox --version)"
 test "$installed_cli_version" = "$latest_cli_version"
 ```
 
-Always use the latest published CLI. CLI 0.0.5 adds organization discovery from the API key,
-Hermes-aware template metadata, permanent paused sandboxes, and same-sandbox follow-ups.
+Always use the latest published CLI. CLI 0.0.10 adds per-run Hermes email and Telegram channels,
+Supabase user authorization, and removes the retired run-chat commands.
+CLI 0.0.9 added 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_...
 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`.
-The CLI derives the organization automatically from `SANBOX_API_KEY`; use an organization-scoped
-key that has access to exactly one organization.
+`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
@@ -44,7 +82,46 @@ sanbox doctor --json
 
 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"`. Hermes service templates are always-on.
+`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. A Hermes template
+declares which optional channels its runs may activate:
+
+```bash
+sanbox templates create \
+  --name "Customer assistant" \
+  --harness hermes \
+  --model-provider openai \
+  --model '<model-id>' \
+  --channel email \
+  --channel telegram
+```
+
+Omit both `--channel` flags for a WebUI-only computer. Channel credentials never belong to the
+template.
+
+## Create A Browser Use Template
+
+Browser Use runs local headless Chromium inside the Firecracker sandbox. It requires OpenAI,
+Anthropic, Google Gemini, or Hetzner Inference 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 are one-shot agent executions.
 
 ## Run Idempotently
 
@@ -64,6 +141,51 @@ sanbox run "Review this repo and write output/report.md" \
 
 Repeat `--input` for files, directories, or globs. The CLI excludes common secrets and applies `.sanboxignore`. `--include` is a deprecated compatibility alias.
 
+For a Hermes template that allows `email`, optionally request an address from one of the AgentMail
+domains listed in the Sanbox console:
+
+```bash
+sanbox run "Handle customer email for this project" \
+  --template "$SANBOX_TEMPLATE" \
+  --email-address research-agent@agentmail.to \
+  --json
+```
+
+`--email-address` is optional. When supplied, AgentMail must be connected and Sanbox does not
+generate a fallback address; use `agentmail.to` or one of the domains listed for the connected Pod.
+
+For a Hermes template that allows `telegram`, pass the bot token and at least one numeric user ID on
+the run. Both values are optional unless the run needs Telegram:
+
+```bash
+sanbox run "Handle Telegram messages for this project" \
+  --template "$SANBOX_TEMPLATE" \
+  --telegram-bot-token '<telegram-bot-token>' \
+  --telegram-allowed-user '<numeric-telegram-user-id>' \
+  --json
+```
+
+You can set `SANBOX_TELEGRAM_BOT_TOKEN` instead of passing `--telegram-bot-token`. Do not use both.
+
+For a long-running Hermes Computer that should act as one Supabase user, provide that user's
+Supabase Auth UUID. Sanbox automatically uses the organization's connected Supabase project:
+
+```bash
+sanbox run "Act as this user's procurement assistant" \
+  --template "$SANBOX_TEMPLATE" \
+  --external-run-id "hermes:<tenant-id>:<user-id>" \
+  --supabase-user-id "<supabase-auth-user-uuid>" \
+  --json
+
+sanbox runs supabase authorize <run-id> --open
+```
+
+The run stays in `awaiting_grant` until the expected Supabase user approves the browser consent
+flow. Without `--open`, the authorize command prints the URL for copying into any browser. The
+callback lands on a Sanbox-hosted completion page, so a CLI demo does not need a customer web app.
+Customer integrations may use `--return-url <https-url>` when its origin matches the return origin
+configured on the organization Supabase connection.
+
 Reuse the same external ID when retrying an ambiguous submission. To stream activity, replace `--wait --json` with `--jsonl`. Ctrl-C detaches without canceling unless `--cancel-on-interrupt` is supplied.
 
 ## Inspect And Recover
@@ -91,21 +213,53 @@ 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 messages <run-id> --json
-sanbox runs message <run-id> "Summarize the retained output" --wait --json
+sanbox runs share <run-id> --expires 1h --json
+sanbox runs shares <run-id> --json
+sanbox runs unshare <run-id> <access-point-id> --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 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. Before resuming, require
+`sandbox_state: "paused"` and a positive `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>
+```
 
-Completed runs pause into a durable Firecracker snapshot. `sanbox runs message <run-id> --message "..."`
-resumes the same writable sandbox and OpenCode session, then pauses it again. There is no retention
-TTL; paused sandboxes and their artifacts remain available until explicitly deleted.
+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.
 
-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.
+OpenCode and Browser Use runs are one-shot agent executions. Create a new run for additional agent
+work. A persisted sandbox can still be resumed manually for inspection when a snapshot exists.
 
 ## Batch Work
 

package/dist/api.js

@@ -150,6 +150,21 @@ export class SanboxClient {
     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" });
+    }
     async listTemplates() {
         return this.request(await this.orgPath("/templates"));
     }
@@ -168,6 +183,18 @@ export class SanboxClient {
     async getRun(runId, signal) {
         return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}`), { signal });
     }
+    async authorizeRunSupabase(runId, returnUrl) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/supabase/authorize`), {
+            method: "POST",
+            body: JSON.stringify(returnUrl ? { return_url: returnUrl } : {})
+        });
+    }
+    async createSSHSession(runId, publicKey) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/ssh-sessions`), {
+            method: "POST",
+            body: JSON.stringify({ public_key: publicKey })
+        });
+    }
     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 });
     }
@@ -177,18 +204,33 @@ export class SanboxClient {
             body: "{}"
         });
     }
-    async sendMessage(runId, message, payload = {}) {
-        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/messages`), {
+    async resumeRun(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/resume`), {
             method: "POST",
-            body: JSON.stringify({ message, payload })
+            body: "{}"
         });
     }
-    async listMessages(runId) {
-        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/messages`));
+    async pauseRun(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/pause`), {
+            method: "POST",
+            body: "{}"
+        });
     }
     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)
+        });
+    }
+    async revokeFileAccessPoint(runId, accessPointId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/file-access-points/${encodeURIComponent(accessPointId)}`), { method: "DELETE" });
+    }
     async downloadArtifact(runId, artifactPath) {
         return this.rawRequest(`${await this.orgPath(`/runs/${encodeURIComponent(runId)}/artifacts`)}?path=${encodeURIComponent(artifactPath)}`);
     }

package/dist/args.js

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