@sanlabs/sanbox-cli 0.0.5 → 0.0.9

package/README.md

@@ -15,23 +15,60 @@ 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.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_...
 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 +81,32 @@ 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.
+
+## 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
 
@@ -91,21 +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.
-
-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 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

@@ -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,12 @@ export class SanboxClient {
     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 })
+        });
+    }
     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,6 +198,18 @@ export class SanboxClient {
             body: "{}"
         });
     }
+    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",
@@ -189,6 +222,18 @@ export class SanboxClient {
     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,10 @@
-const multiFlags = new Set(["input", "include", "artifact", "telegram-allowed-user"]);
+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 = [];