@lizard-build/cli 4.0.45 → 4.0.46

package/skill-data/core/references/sandboxes.md

@@ -21,15 +21,24 @@ The details behind the Sandboxes section of the core guide. Read the part the ta
 | `-t` | What is inside |
 |---|---|
 | `base` (default) | Python 3.11 on Alpine Linux, nothing else |
-| `interpreter` | A Python code-interpreter environment |
-| `codex` | Coding agents: see [Coding agents](#coding-agents) |
-| `desktop` | A graphical desktop with Chromium: see [Desktop](#desktop-computer-use) |
+| `interpreter` | Python 3.11 with numpy, pandas, matplotlib, scipy, requests, httpx and IPython; Node 22 and `lizard` |
+| `codex`, `claude`, `opencode`, `pi`, `prime` | One coding agent each (Codex, Claude Code, OpenCode, pi, Prime Agent) on Node 22, with git, python3, ripgrep, curl, jq and `lizard`: see [Coding agents](#coding-agents) |
+| `desktop` | A graphical desktop with Chromium, plus Codex and `lizard`: see [Desktop](#desktop-computer-use) |
 
-The platform validates the name; `lizard sandbox create --help --json` lists the templates this CLI knows.
+An unknown name fails and lists the region's `availableTemplates`. `--with-token` on `sandbox create` signs in the sandbox's own `lizard` with a new key limited to the sandbox's project, deleted with the sandbox (only useful on templates that ship `lizard`).
 
 ## Running commands
 
-`lizard sandbox exec <id> -- <cmd> [args...]` runs the command through `sh -c` in the sandbox, streams stdout and stderr, and exits with the command's exit code. In JSON mode it prints the raw output without the `$ <cmd>` header. Each call is a new process, so `cd` and exported variables don't carry over: chain steps in one call, e.g. `lizard sandbox exec <id> -- sh -c 'cd /workspace && npm test'`, and keep results in files.
+`lizard sandbox exec <id> -- <cmd> [args...]` runs the command in the sandbox, streams stdout and stderr, and exits with the command's exit code. Each argument stays one word: `exec <id> 'cd /workspace && npm test'` fails with `not found`, so put a shell line in `-- sh -c '…'`. Without a terminal it prints the raw output without the `$ <cmd>` header. Each call is a new process that starts in `/root`, so `cd` and exported variables don't carry over: chain steps in one call, e.g. `lizard sandbox exec <id> -- sh -c 'cd /workspace && npm test'`, and keep results in files.
+
+A call gives up after 150 seconds (exit `4`, `EXEC_TIMEOUT`; the command may still be running) and keeps at most 512 KB of output. Run longer work in the background and poll a log:
+
+```
+lizard sandbox exec <id> -- sh -c 'cd /workspace && nohup npm run build > build.log 2>&1 &'
+lizard sandbox exec <id> -- tail -n 50 /workspace/build.log
+```
+
+Ports 25, 465, 587 and 2525 are blocked for outbound traffic: sandboxes cannot send mail directly.
 
 ## Files
 
@@ -41,15 +50,20 @@ lizard sandbox files get <id> <remote> <local>
 lizard sandbox files rm <id> <path>
 ```
 
-`/workspace` is the working directory: `ssh` starts there and volumes mount there. `files put` and `files get` keep binary files intact.
+`ssh` starts in `/workspace` and volumes mount there; `exec` starts in `/root`, so use absolute paths. `files put` and `files get` keep binary files intact. `files get` and `files cat` stop at 15 MiB (HTTP 413); `files put` takes about 110 MB.
 
 ## Ports
 
-`lizard sandbox expose <id> <port>` publishes a port inside the sandbox on an HTTPS URL; `lizard sandbox unexpose <id> <port>` removes it. The URL carries the sandbox's access token, so treat it like a password. The platform keeps one port for itself and refuses to expose it.
+`lizard sandbox expose <id> <port> --json` publishes a port inside the sandbox on an HTTPS URL, `https://<id>-<port>.sandbox.<region>.onlizard.com/?lizard_token=…`; `lizard sandbox unexpose <id> <port>` removes it. One token opens every port of that sandbox, so treat the URL like a password. The server can listen on `127.0.0.1` or `0.0.0.0`.
+
+- A browser opening the URL trades the token for a cookie and is redirected, so the link just works.
+- `curl` gets an empty `302`, and `curl -L` without a cookie jar gets `401`. From a script send the header instead: `curl -H "X-Lizard-Access-Token: <accessToken>" https://<hostname>/` (both come in the `--json` output), or keep cookies: `curl -sL -c jar -b jar '<url>'`.
+- A `POST` with `?lizard_token=` passes straight through, so webhooks work.
+- Port `49983` is the platform's and can't be exposed.
 
 ## Lifetime
 
-`lizard sandbox create` sends a five-minute lifetime (`300000` milliseconds) by default. Pass `--timeout 0` to create a sandbox without expiration, or pass an integer up to `2147483647` milliseconds. This is a lifetime, not an idle timer: commands do not reset it. `lizard sandbox timeout <id> <ms>` sets a new lifetime of at least `1000` milliseconds. Pausing a sandbox freezes its remaining lifetime; resuming continues from it (see [private snapshots and pause/resume](#snapshots-and-pauseresume)). The CLI has no sandbox fork command. Use volumes for persistent files.
+`lizard sandbox create` and `lizard sandbox restore` send a five-minute lifetime (`300000` milliseconds) by default. Pass `--timeout 0` to create a sandbox without a deadline (the VM itself still stops after 596 hours), or pass an integer up to `2147483647` milliseconds. This is a lifetime, not an idle timer: commands do not reset it. `lizard sandbox timeout <id> <ms>` sets a new lifetime of at least `1000` milliseconds. Pausing a sandbox freezes its remaining lifetime; resuming continues from it (see [private snapshots and pause/resume](#snapshots-and-pauseresume)). The CLI has no sandbox fork command. Use volumes for persistent files.
 
 ## Size and pricing
 
@@ -61,9 +75,11 @@ lizard sandbox files rm <id> <path>
 | `medium` (default) | 4 | 8 GiB | 20 GB | $0.0324/h |
 | `large` | 8 | 16 GiB | 50 GB | $0.0648/h |
 
-Prices are per hour, billed per second while the sandbox runs, flat by size: measured CPU/RAM is not charged, disk is included, and egress is included up to 2 TB per account over a rolling 30 days (past that, the account's sandboxes lose outbound network until the total drops). A paused sandbox costs nothing. Attached volumes bill separately. `--size` cannot be combined with `--snapshot`: a snapshot restores at the size it was captured at (see [private snapshots](#snapshots-and-pauseresume)).
+Prices are per hour, billed per second while the sandbox runs, flat by size: measured CPU/RAM is not charged, and disk and egress are included. A paused sandbox costs nothing. Attached volumes bill separately. `--size` cannot be combined with `--snapshot`: a snapshot restores at the size it was captured at (see [private snapshots](#snapshots-and-pauseresume)).
 
-Sandboxes run as Firecracker microVMs, each with its own kernel. A sandbox that attaches an existing pod-backed volume, or restores an older pod snapshot, runs as a Kubernetes pod instead.
+Sandboxes run as Firecracker microVMs, each with its own kernel. A sandbox that attaches an existing pod-backed volume, or restores an older pod snapshot, runs as a Kubernetes pod instead; a Firecracker start that fails without a volume also falls back to a pod. The create JSON's `runtime` says which.
+
+An account runs at most 5 sandboxes at once on a trial and 100 after its first paid invoice (paused ones don't count), with limits on starts per minute, hour and day. Enterprise accounts have a cap per workspace instead (50 by default). Over a limit the API answers 429 `SANDBOX_LIMIT_REACHED` or `SANDBOX_RATE_LIMITED` (with `retryAfterS`).
 
 ## Interactive shell
 
@@ -75,19 +91,26 @@ exit code.
 
 ## Coding agents
 
-Run a coding agent inside a sandbox (use `-t codex`) on the user's own credentials:
+Run a coding agent in a sandbox made from its template (`-t codex`, `-t claude`, `-t opencode`, `-t pi`, `-t prime`) on the user's own credentials. Give the sandbox a real lifetime (`--timeout 3600000`): at five minutes it is deleted with the agent mid-task. Another template with Node installs the agent at the first prompt, which is slow; one without Node can't run agents.
 
 - `lizard agents` — your account's credentials and which agents can run. Connect once (here or in the
   dashboard: Account settings › Agents); every sandbox and every agent that accepts it uses it.
 - `lizard agents login chatgpt` — ChatGPT subscription via device code.
   `lizard agents add claude` (token from `claude setup-token`), `add anthropic|openai|openrouter|llmgateway|deepseek` for API keys.
 - `lizard agents use <agent> --credential … --model … --effort …` — per-agent defaults.
-- `lizard sandbox prompt <id> --agent codex|claude|pi|opencode|prime "task"` — streams tool calls and
-  the answer; `-c <conversation>` continues one; `--no-wait` returns at once.
+- `lizard sandbox prompt <id> --agent codex|claude|pi|opencode|prime "task" --json` — one JSON event per
+  line: tool calls, then a `response` event whose `text` is the answer, then `finished` or `failed`.
+  `-c <conversation>` continues one; `--cwd` (default `/workspace`), `-m <model>`, `--effort
+  minimal|low|medium|high|xhigh`. `--no-wait` returns at once, and the CLI has no command to read the
+  answer later, so prefer waiting.
 - `lizard sandbox conversations <id>`, `lizard sandbox interrupt <id> [-c <conversation>]`.
 
 Codex and Claude Code use one credential at a time; pi, OpenCode and Prime use every connected one
-they accept. Sandboxes never receive a subscription's refresh token, only a short-lived access token.
+they accept. A ChatGPT login reaches the sandbox only as a short-lived access token. API keys and the
+Claude token go in as they are (`ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`), so any code in the
+sandbox can read them. `lizard agents` needs a full sign-in: a key limited to projects gets 403
+`ACCOUNT_SCOPE_REQUIRED`. A failed agent login is not always the user's credential: report the
+error as it is.
 
 Use `sandbox exec` to read a log file written by your process.
 
@@ -117,7 +140,7 @@ lizard sandbox exec <id> -- lizard-desktop screenshot | grep -E '^[A-Za-z0-9+/=]
 lizard sandbox exec <id> -- lizard-desktop screenshot --path   # writes the PNG to a file in the sandbox, prints its path
 ```
 
-`lizard-desktop screenshot` prints the PNG as base64 wrapped at 76 columns; the `grep` keeps only those lines (it drops the `$ <cmd>` header `sandbox exec` prints). Use `--path` to save the PNG, then download that path with `lizard sandbox files get <id> <remote-path> screen.png`. `files put` and `files get` preserve binary files.
+`lizard-desktop screenshot` prints the PNG as base64 wrapped at 76 columns; the `grep` keeps only those lines (in a terminal it drops the `$ <cmd>` header `sandbox exec` prints). Use `--path` to save the PNG, then download that path with `lizard sandbox files get <id> <remote-path> screen.png`. `files put` and `files get` preserve binary files.
 
 ## Volumes
 
@@ -126,19 +149,21 @@ Use `lizard volume create <name> --size <gb> --project <project>` for persistent
 Persistent volumes for sandboxes. A volume's name is its key within the project; every command takes a name or ID.
 
 ```
-lizard volume create <name> [--size <gb>] [--region <code>]   # default 5 GB; region must match the sandbox's
+lizard volume create <name> [--size <gb>] [--region <code>]   # default 5 GB; a sandbox with --volume starts in its region
 lizard volume list --json                                     # name, sizeGb, status, attachedTo
 lizard volume resize <name> --size <gb>                       # grow in place
 lizard volume rm <name> [-y]                                  # refused while attached; delete the sandbox first
 lizard sandbox create --volume <name>                         # attach at create time
 ```
 
+A volume attaches to one sandbox at a time (409 `Volume is already attached to another sandbox`); a paused sandbox keeps its volume. A workspace holds 200 GB of volumes by default (`volume_quota_exceeded`). For a deployed service's volume, see `lizard volume create <name> --service <svc>` in the core guide.
+
 `volume resize` is online: an attached sandbox keeps running, and its `/workspace` shows the new size right away. A volume grown while detached gets the new size when a sandbox next mounts it. Firecracker volumes (the default) only grow; asking for less fails with `volume_shrink_unsupported`. A Kubernetes volume can also shrink if at least 10% of the new size stays free (`volume_too_full_to_shrink` otherwise). The size limit (`volume_too_large`) and the workspace's volume quota apply as at create. `The volume is not ready` (HTTP 409) right after create means retry in a few seconds.
 
 ## Snapshots and pause/resume
 
-- `lizard sandbox snapshot <sandbox-id> --name my-app` saves files and running memory privately. The snapshot is yours: by default it restores into any of your projects and workspaces; `--scope workspace` keeps it to the sandbox's workspace and `--scope project` to its project, and `sandbox snapshot-scope <id> <user|workspace|project>` changes that later. A Firecracker snapshot is ready as soon as the capture ends. A snapshot of a pod sandbox keeps **five** independent copies warm; `--warm 1..10` changes that count. It waits until ready; `--no-wait` returns the queued capture.
-- `lizard sandbox restore <snapshot-id> [--project <project>]` starts a new sandbox from a warm copy, in the snapshot's project unless `--project` names another. `--volume <volume>` mounts a volume at `/workspace` in the restored sandbox (Firecracker snapshots of a sandbox that had no volume attached; the volume must be in the snapshot's region). `sandbox create --snapshot <id> --project <project> [--volume <volume>]` also works. Restores stay in the snapshot's region. A Firecracker snapshot restores at its source's size and bills flat at that size; a pod snapshot runs on the machine it was captured on and bills by measured usage. `--size` with `--snapshot` is an error.
+- `lizard sandbox snapshot <sandbox-id> --name my-app` saves files and running memory. You and the members of its project can list, restore and delete it; only you change its scope. By default it restores into any of your projects and workspaces; `--scope workspace` keeps it to the sandbox's workspace and `--scope project` to its project, and `sandbox snapshot-scope <id> <user|workspace|project>` changes that later. A Firecracker snapshot is ready as soon as the capture ends. A snapshot of a pod sandbox keeps **five** independent copies warm; `--warm 1..10` changes that count. It waits until ready; `--no-wait` returns the queued capture.
+- `lizard sandbox restore <snapshot-id> [--project <project>] [--timeout <ms>]` starts a new sandbox from a warm copy (five-minute lifetime by default), in the snapshot's project unless `--project` names another. `--volume <volume>` mounts a volume at `/workspace` in the restored sandbox (Firecracker snapshots of a sandbox that had no volume attached; the volume must be in the snapshot's region). `sandbox create --snapshot <id> --project <project> [--volume <volume>]` also works. Restores stay in the snapshot's region. A Firecracker snapshot restores at its source's size and bills flat at that size; a pod snapshot runs on the machine it was captured on and bills by measured usage. `--size` with `--snapshot` is an error.
 - `lizard sandbox snapshots --project <project>` lists a project's snapshots; `--mine` lists every snapshot you took. `sandbox snapshot-warm <id> <count>` changes capacity. `sandbox snapshot-rm <id>` deletes the snapshot and free copies, preserving already running sandboxes.
 - `lizard sandbox pause <id>` snapshots and stops a Firecracker VM (a pod sandbox is checkpointed with CRIU), stops billing, and freezes its remaining lifetime. `sandbox resume <id>` restores the same sandbox ID, files, processes, memory, published ports, and remaining lifetime. Paused sandboxes keep no warm copies; resume includes a cold restore. Both support `--no-wait`.
 - Disconnect clients and terminals and stop workspace writes before capturing or pausing. On a pod sandbox, active TCP connections and unsupported CRIU process state cause a clear failure. To reuse one snapshot across sandboxes that each keep their own data, snapshot a sandbox with no volume attached and pass `--volume` on each restore; a snapshot taken with a volume attached cannot take a different one.

package/skill-data/core/references/sdk.md

@@ -22,10 +22,12 @@ Use Lizard SDK when the user's own code creates and drives sandboxes or manages
 
 | SDK | Install | Requires |
 |---|---|---|
-| TypeScript | `npm install @lizard-build/sdk` | Node.js 18+ |
+| TypeScript | `npm install @lizard-build/sdk` | Node.js 18.16+ |
 | Python | `pip install lizard-sdk` | Python 3.10+ |
 
-The SDK reads `LIZARD_API_KEY` and, optionally, `LIZARD_API_URL` (default `https://lizard.build`); `apiKey` / `api_key` and `apiUrl` / `api_url` override them. It does not load `.env` files. Create a key with `lizard keys create <name> --project <project> --json`: a key limited to one project is safest when the code runs somewhere else. The key is shown once.
+This guide matches SDK 0.1.59 or later.
+
+The SDK reads `LIZARD_API_KEY` and, optionally, `LIZARD_API_URL` (default `https://lizard.build`); `apiKey` / `api_key` and `apiUrl` / `api_url` override them. It does not load `.env` files. Create a key with `lizard keys create <name> --project <project> --json`: a key limited to one project is safest when the code runs somewhere else. The key is shown once; pass it to the program as `LIZARD_API_KEY`. The `lizard` CLI's own sign-in is not read by the SDK. Static methods (`Sandbox.connect`, `Sandbox.list`, `Sandbox.restore`, `Sandbox.deleteSnapshot`, `CodeSandbox.create`) read `LIZARD_API_KEY` too, not the key given to `new Lizard`: on a server holding several keys pass `apiKey` / `api_key` to them, or use `lizard.connect(id)`.
 
 Sandboxes and volumes need a project: `new Lizard({ project })` / `Lizard(project=...)` takes its ID, slug or unique name; use the exact ID when names are ambiguous. Platform APIs work without one.
 
@@ -34,15 +36,17 @@ Options for `create()` (TypeScript / Python):
 | Option | Purpose |
 |---|---|
 | `size` | `small` (2 vCPU / 4 GB, $0.0162/h), `medium` (4 vCPU / 8 GB, $0.0324/h, default), `large` (8 vCPU / 16 GB, $0.0648/h) |
-| `timeoutMs` / `timeout_ms` | Lifetime; default 300,000 ms (5 minutes); `0` means no limit |
-| `envs` | Environment variables for every command in the sandbox |
-| `metadata` | Your own string labels, returned by `getInfo()` / `get_info()` |
+| `timeoutMs` / `timeout_ms` | Lifetime; default 300,000 ms (5 minutes); `0` means no deadline (the VM still stops after 596 hours) |
+| `envs` | Environment variables for every command in the sandbox (up to 256) |
+| `metadata` | Your own string labels, returned by `getInfo()` / `get_info()` (up to 64) |
 | `region` | Region ID; omit to use the platform default |
 | `volumeName` / `volume_name`, `volumeId` / `volume_id` | Attach a persistent volume at `/workspace` |
 | `snapshotId` / `snapshot_id` | Start from a saved snapshot |
-| `lizardToken` / `lizard_token` | A Lizard key for tools inside the sandbox; any code there can read it |
+| `lizardToken` / `lizard_token` | One of your own keys: the sandbox's `lizard` gets a new key limited to its project, deleted with it. Someone else's key is skipped without an error |
+
+Templates: `base` (default), `interpreter` (Python with data libraries, plus Node 22), `codex`, `claude`, `opencode`, `pi`, `prime` (one coding agent each), `desktop`. The SDK and CLI give a sandbox 5 minutes by default; the raw API and the dashboard give none. Commands do not reset the deadline. Pricing is flat by size, billed per second while the sandbox runs; a sandbox restored from a snapshot runs at the source's size and is billed at that size; volumes bill separately.
 
-Templates: `base` (default), `interpreter` (Python and common data libraries), `codex`, `desktop`. The SDK and CLI give a sandbox 5 minutes by default; the raw API and the dashboard give none. Commands do not reset the deadline. Pricing is flat by size, billed per second while the sandbox runs; a sandbox started from a snapshot is billed by measured usage, and volumes bill separately.
+An account runs at most 5 sandboxes at once on a trial and 100 after its first paid invoice, with limits on starts per minute, hour and day: over a limit, a `LizardError` with status 429 and `code` `SANDBOX_LIMIT_REACHED` or `SANDBOX_RATE_LIMITED`. More than 32 commands at once in one sandbox gives `EXEC_LIMIT_REACHED`.
 
 ## Quickstart
 
@@ -80,14 +84,15 @@ Always kill the sandbox when done: `try/finally` in TypeScript, the `with` block
 `process.exec(cmd)` / `process.exec_(cmd)` returns stdout, stderr and the exit code. A nonzero exit code is a result to check; request failures throw or raise.
 
 - `onStdout` / `onStderr` (`on_stdout` / `on_stderr`) stream output while the call still waits for the end.
-- `timeoutMs` / `timeout_ms` bounds one command: 1–600 seconds.
+- `timeoutMs` / `timeout_ms` bounds one command: 1–600 seconds, **60 seconds by default**. Past it the SDK gives up with a `DOMException` named `TimeoutError` (TypeScript) or `httpx.ReadTimeout` (Python), not a `LizardError`. Pass it for anything slower, such as `pip install`; run longer jobs with `nohup … &` and poll a log.
+- Output keeps 512 KiB per stream, then `truncated` is set.
 - `envs`, `workdir` and `user` (e.g. `user: 'user'`, the template's unprivileged account) apply to that command only.
 - `onPid` / `on_pid` gives the pid before any output; `process.list()` lists commands and `process.kill(pid, 'SIGKILL')` signals the whole process tree.
 - An argv array runs the binary without a shell, so text from a model or a user cannot run commands.
 
 ## Files
 
-`fs.write`, `fs.read`, `fs.readBytes` / `fs.read_bytes`, `fs.list`, `fs.stat`, `fs.makeDir` / `fs.make_dir`, `fs.move`, `fs.remove`. Use absolute paths. Writes take text or bytes; bytes are stored exactly, so read binary files back with `readBytes()` / `read_bytes()`. A missing path raises `NotFoundError`. `list()` and `stat()` entries carry `type`, `size`, `mode`, `permissions`, `owner`, `group` and `modTime`. File watching is not available yet.
+`fs.write`, `fs.read`, `fs.readBytes` / `fs.read_bytes`, `fs.list`, `fs.stat`, `fs.makeDir` / `fs.make_dir`, `fs.move`, `fs.remove`. Use absolute paths. Writes take text or bytes; bytes are stored exactly, so read binary files back with `readBytes()` / `read_bytes()`. A missing path raises `NotFoundError`. `list()` and `stat()` entries carry `type`, `size`, `mode`, `permissions`, `owner`, `group` and `modTime` (`mod_time` in Python). Reads stop at 15 MB (HTTP 413). File watching is not available yet.
 
 ## Stateful code (CodeSandbox)
 
@@ -99,8 +104,9 @@ import { CodeSandbox } from '@lizard-build/sdk'
 const sandbox = await CodeSandbox.create({ projectId })
 try {
   await sandbox.runCode('import pandas as pd\ndf = pd.DataFrame({"x": [1, 2, 3]})')
-  const run = await sandbox.runCode('df.x.sum()')
-  console.log(run.results[0].data)   // "6"
+  const run = await sandbox.runCode('int(df.x.sum())')
+  const out = run.results[0]
+  if (out?.type === 'result') console.log(out.data)   // "6"
 } finally {
   await sandbox.kill()
 }
@@ -111,10 +117,10 @@ from lizard import CodeSandbox
 
 with CodeSandbox.create(project_id=project_id) as sandbox:
     sandbox.run_code('import pandas as pd\ndf = pd.DataFrame({"x": [1, 2, 3]})')
-    print(sandbox.run_code("df.x.sum()").results[0].data)   # "6"
+    print(sandbox.run_code("int(df.x.sum())").results[0].data)   # "6"
 ```
 
-An `Execution` has `stdout`, `stderr`, `results` (the last expression as text, charts and images as base64 PNG, HTML), `error` (`name`, `message`, `traceback`) and `executionCount`. A code error is a result, not an exception. `createContext()` / `create_context()` starts a separate kernel with its own state; `restartContext` clears one. `timeoutMs` (default 60 s) bounds one call: the kernel is interrupted, keeps its state, and `error.name` is `TimeoutError`. `bash` and `javascript` run as fresh processes with no state; `javascript` needs `node`, which `interpreter` does not ship.
+An `Execution` has `stdout`, `stderr`, `results` (the last expression as text, charts and images as base64 PNG, HTML), `error` (`name`, `message`, `traceback`) and `executionCount`. A code error is a result, not an exception. `createContext()` / `create_context()` starts a separate kernel with its own state; `restartContext` clears one. `timeoutMs` (default 60 s) bounds one call: the kernel is interrupted, keeps its state, and `error.name` is `TimeoutError`. `bash` and `javascript` run as fresh processes with no state; `javascript` uses the template's Node 22. With numpy 2, a bare `df.x.sum()` displays as `np.int64(6)`: convert to `int` for plain output.
 
 ## Ports
 
@@ -148,7 +154,7 @@ lizard.volumes.get_or_create("agent-files", size_gb=10)
 sandbox = lizard.create("base", volume_name="agent-files")
 ```
 
-Names are unique within a project: `getOrCreate` returns the existing volume, `create` raises `ConflictError`. New volumes are 1–50 GB (default 5). `volumes.list()`, `volumes.get(nameOrId)` and `volumes.delete(nameOrId)` (deletes the files too). To grow a volume, use `lizard volume resize` (see the sandboxes reference).
+Names are unique within a project: `getOrCreate` returns the existing volume, `create` raises `ConflictError`. New volumes are 1–50 GB (default 5). `volumes.list()`, `volumes.get(nameOrId)` and `volumes.delete(nameOrId)` (deletes the files too). Grow one with `lizard.volumes.resize('agent-files', 20)` / `lizard.volumes.resize("agent-files", 20)`; volumes only grow.
 
 ## Lifecycle, pause, snapshots and fork
 
@@ -162,7 +168,7 @@ Names are unique within a project: `getOrCreate` returns the existing volume, `c
 | Pause and resume (memory and processes kept, billing stops) | `pause()`, `resume()`, `waitForStatus(s)` | `pause()`, `resume()`, `wait_for_status(s)` |
 | Snapshot (about 2 s, the source keeps running) | `snapshot(name)` | `snapshot(name)` |
 | Start a sandbox from a snapshot (about 0.4 s) | `Sandbox.restore(id)` | `Sandbox.restore(id)` |
-| Live copies of a running sandbox (1–10) | `fork({ count })` | `fork(count=...)` |
+| Live copies of a running sandbox (each counts toward the running limit) | `fork({ count })` | `fork(count=...)` |
 
 A snapshot belongs to the user who took it and restores into any project they can use, unless its scope is `workspace` or `project` (`snapshot(name, { scope })`, `Sandbox.setSnapshotScope(id, scope)`). To start many sandboxes that each keep their own files from one snapshot, take it without a volume and pass `volumeId` to each `restore`. A sandbox with a volume cannot be forked. `fork()` returns one entry per copy, with `sandbox` or `error` (for example the account's sandbox limit). Delete snapshots with `Sandbox.deleteSnapshot(id)`; sandboxes already restored keep running.
 
@@ -172,24 +178,30 @@ The `desktop` template has a graphical desktop with Chromium on `DISPLAY=:1`. `s
 
 ## Sandboxes for your own users
 
-Give each of your users a workspace, a project and a key scoped to that workspace. Run this on your trusted server:
+Each sandbox is its own microVM, so running every customer's code in a sandbox of its own already keeps customers apart: one project, one key limited to it, a sandbox per customer or per task tagged with `metadata` (`{ customerId }`), killed when done. That is the default.
+
+Add a workspace and a key per customer only when customers get Lizard access of their own (their code calls Lizard, or you hand them a key). Creating workspaces needs an unscoped key; a scoped key gets 403. Run this on your trusted server:
 
 ```ts
 const lizard = new Lizard({})
 const workspace = await lizard.workspaces.create({ name: 'user-123' })
-await lizard.projects.create({ workspaceId: workspace.id, name: 'default' })
+const project = await lizard.projects.create({ workspaceId: workspace.id, name: 'default' })
 const key = await lizard.apiKeys.create({ name: 'user-123', workspaces: [workspace.id] })
-// Store key.key now: the API returns it only once.
+// Store key.key and project.id now: the API returns the key only once.
+const forUser = new Lizard({ apiKey: key.key, project: project.id })
 ```
 
 ```python
 lizard = Lizard()
 workspace = lizard.workspaces.create(name="user-123")
-lizard.projects.create(workspace_id=workspace.id, name="default")
+project = lizard.projects.create(workspace_id=workspace.id, name="default")
 key = lizard.api_keys.create(name="user-123", workspaces=[workspace.id])
+for_user = Lizard(api_key=key.key, project=project.id)
 ```
 
-A key without scopes reaches everything the account can; `workspaces` or `projects` limit it, and a scoped key cannot create a broader one. Scoped keys cannot see account billing (HTTP 403 `ACCOUNT_SCOPE_REQUIRED`). `workspaces.delete()` needs an empty workspace unless you pass `force`.
+Keep `project.id`: every user's project is named `default`, so the name is ambiguous for your own key. Every user workspace bills to your account and counts toward your sandbox limits. A key without scopes reaches everything the account can; `workspaces` or `projects` limit it, and a scoped key cannot create a broader one. Scoped keys cannot see account billing (HTTP 403 `ACCOUNT_SCOPE_REQUIRED`). 
+
+`workspaces.delete()` needs an empty workspace unless you pass `force`, and `force` removes apps, addons and projects but leaves sandboxes running and volumes and snapshots in place: kill the workspace's sandboxes and delete its volumes and snapshots first.
 
 ## Platform APIs
 
@@ -204,7 +216,7 @@ The same client manages the rest of Lizard: `projects`, `services` (deploy, insp
 | Error | Meaning |
 |---|---|
 | `PaymentRequiredError` | HTTP 402: the account must start Pro, start it now, or pay an invoice. Show `message` as is and open `url`; retry after the user pays |
-| `AuthenticationError` | HTTP 401 or 403: bad key or no access |
+| `AuthenticationError` | HTTP 401 or 403: bad key, no access, or a refusal such as a volume quota, a snapshot's scope or `ACCOUNT_SCOPE_REQUIRED`: check `code` |
 | `NotFoundError` | HTTP 404 |
 | `ConflictError` | HTTP 409, such as a volume name in use |
 | `TimeoutError` | HTTP 408 or 504 |

package/src/commands/add.ts

@@ -273,7 +273,6 @@ async function runAdd(input: AddInput): Promise<void> {
         if (opts.variables?.length) {
           info(chalk.yellow("Warning: --variables is ignored for managed addons"));
         }
-        const isSingle = databases.length === 1;
         for (const db of databases) {
           const cat = CATALOG.find((c) => c.name === db)!;
           info(`Adding ${chalk.cyan(cat.label)}...`);
@@ -303,11 +302,8 @@ async function runAdd(input: AddInput): Promise<void> {
             }
           }
 
-          if (isSingle) {
-            try {
-              updateProjectLink({ serviceId: addon.id, serviceName: addon.name });
-            } catch {}
-          }
+          // The folder keeps its service link: linking it to the addon sent the next
+          // `lizard up` / `secrets set` / `logs --build` to a database ("App not found").
         }
         return;
       }

package/src/commands/agents.ts

@@ -3,7 +3,7 @@ import ora from "ora";
 import open from "open";
 import { Command } from "commander";
 import * as p from "@clack/prompts";
-import { api } from "../lib/api.js";
+import { api, APIError } from "../lib/api.js";
 import { success, info, isJSONMode, printJSON, table, timeAgo } from "../lib/format.js";
 
 // Built-in coding agents (platform: server/src/routes/agents.ts), Boat-style.
@@ -185,6 +185,24 @@ function render(e: AgentEvent, verbose: boolean) {
   }
 }
 
+/**
+ * One page of a conversation's events. The agent keeps working in the sandbox while we
+ * watch, so a dropped connection or a 5xx must not end the watch: retry for about two
+ * minutes before giving up.
+ */
+async function pollEvents(id: string, conversationId: string, after: number) {
+  const path = `/api/sandboxes/${id}/events?after=${after}&conversationId=${conversationId}&limit=500`;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await api.get<{ events: AgentEvent[]; next: number }>(path);
+    } catch (e) {
+      const transient = !(e instanceof APIError) || e.status === 429 || e.status >= 500;
+      if (!transient || attempt >= 24) throw e;
+      await sleep(Math.min(1000 * attempt, 5000));
+    }
+  }
+}
+
 export function registerSandboxAgentCommands(sb: Command) {
   sb.command("prompt")
     .argument("<id>", "Sandbox ID")
@@ -223,9 +241,7 @@ Examples:
       });
       let after = 0;
       for (;;) {
-        const r = await api.get<{ events: AgentEvent[]; next: number }>(
-          `/api/sandboxes/${id}/events?after=${after}&conversationId=${started.conversationId}&limit=500`,
-        );
+        const r = await pollEvents(id, started.conversationId, after);
         after = r.next ?? after;
         for (const e of r.events) {
           if (e.promptId !== started.promptId) continue;

package/src/commands/domain.ts

@@ -4,7 +4,7 @@ import { Command } from "commander";
 import { api } from "../lib/api.js";
 import { resolveProjectId } from "../lib/config.js";
 import { getActiveService } from "../lib/resolve.js";
-import { success, isJSONMode, printJSON, table, isTTY } from "../lib/format.js";
+import { success, isJSONMode, printJSON, table, isTTY, info } from "../lib/format.js";
 
 interface DomainResponse {
   ok?: boolean;
@@ -92,7 +92,14 @@ export function registerDomain(program: Command) {
         return;
       }
 
-      // Attach custom hostname
+      // Attach custom hostname. Anything without a dot is a typo or a missing subcommand
+      // (`lizard domain list` once attached a domain literally named "list").
+      if (!/^(?=.{4,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9-]{2,63}$/i.test(hostname)) {
+        throw new Error(
+          `"${hostname}" is not a domain name. Attach a full hostname such as app.example.com; ` +
+            "`lizard domain list` shows the service's domains.",
+        );
+      }
       const result = await api
         .post<DomainResponse>(`/api/apps/${service.id}/domains`, {
           hostname,
@@ -250,6 +257,33 @@ export function registerDomain(program: Command) {
       }
     });
 
+  dom
+    .command("list")
+    .alias("ls")
+    .description("List the service's domains, and custom domains still waiting for DNS verification")
+    .action(async (_opts, sub) => {
+      const opts = sub.optsWithGlobals();
+      const projectId = await resolveProjectId(opts.project);
+      const service = await getActiveService(opts.service, projectId);
+      const r = await api.get<{
+        domains?: string[]; generatedDomain?: string | null; cnameTarget?: string;
+        pending?: { hostname: string; txtRecord: string; txtValue: string; cnameTarget: string }[];
+      }>(`/api/apps/${service.id}/domains`);
+      if (isJSONMode()) return printJSON({ service: service.name, ...r });
+      const active = r.domains ?? [];
+      if (!active.length && !(r.pending ?? []).length) {
+        info(`${service.name} has no domain yet. Generate one: lizard domain --service ${service.name}`);
+        return;
+      }
+      for (const d of active) console.log(`${chalk.green("●")} https://${d}`);
+      for (const p of r.pending ?? []) {
+        console.log(`${chalk.yellow("○")} ${p.hostname} ${chalk.dim("(waiting for DNS)")}`);
+        console.log(chalk.dim(`    TXT   ${p.txtRecord}  ${p.txtValue}`));
+        console.log(chalk.dim(`    CNAME ${p.hostname}  ${p.cnameTarget}`));
+        console.log(chalk.dim(`    then: lizard domain verify ${p.hostname} --service ${service.name}`));
+      }
+    });
+
   dom
     .command("verify")
     .argument("<hostname>", "Custom domain to verify")

package/src/commands/init.ts

@@ -83,6 +83,24 @@ export async function ensureLinked(opts: {
     }
   }
 
+  // A named project may live in any workspace. Look it up everywhere first: the flow
+  // below searches one workspace only and creates the project when that workspace has
+  // no match, which made a duplicate of a project in another workspace (and, for a key
+  // limited to that project, failed with 404 "Project not found").
+  if (opts.projectName && !opts.workspaceFlag) {
+    const lower = opts.projectName.toLowerCase();
+    const all = await api.get<Array<Project & { workspaceId?: string; workspaceName?: string }>>("/api/projects");
+    const matches = all.filter(
+      (pr) => pr.id.toLowerCase() === lower || pr.slug?.toLowerCase() === lower || pr.name.toLowerCase() === lower,
+    );
+    if (matches.length === 1) {
+      const m = matches[0];
+      const link: ProjectLink = { projectId: m.id, projectName: m.name, workspaceId: m.workspaceId, workspaceName: m.workspaceName };
+      setProjectLink(link);
+      return link;
+    }
+  }
+
   // 1. Workspace
   const workspaces = await fetchWorkspaces();
   const workspace = await pickWorkspace({

package/src/commands/metrics.ts

@@ -2,7 +2,7 @@ import chalk from "chalk";
 import { Command } from "commander";
 import { api, withScope, withQuery, APIError, type ResourceScope } from "../lib/api.js";
 import { getProjectLink } from "../lib/config.js";
-import { resolveProjectScope, getActiveServiceWithKind } from "../lib/resolve.js";
+import { resolveProjectScope, getActiveServiceWithKind, lookupProjectWorkspace } from "../lib/resolve.js";
 import { info, fail, isJSONMode, printJSON, table, timeAgo } from "../lib/format.js";
 
 // Shapes returned by /api/apps/:id/metrics and /api/projects/:id/metrics.
@@ -584,6 +584,11 @@ function fmtPeriodDate(ms: number): string {
 }
 
 async function showCost(projectId: string, scope: ResourceScope) {
+  // Scopes for other commands skip the workspace lookup (their routes ignore it), so an
+  // unlinked folder or --project arrives here without one: fetch it, cost needs it.
+  if (!scope.workspaceId) {
+    scope = { ...scope, workspaceId: (await lookupProjectWorkspace(projectId))?.workspaceId ?? null };
+  }
   if (!scope.workspaceId) {
     fail("Could not resolve the workspace for this project. Run `lizard link` first.");
   }
@@ -599,7 +604,11 @@ async function showCost(projectId: string, scope: ResourceScope) {
     ]);
   } catch (e) {
     if (e instanceof APIError && e.status === 403) {
-      fail("Billing is only visible to the workspace owner.", 2);
+      // A key limited to some projects can't read the workspace's billing at all; only
+      // a plain 403 means "not the owner".
+      fail(/API key/i.test(e.message)
+        ? `${e.message} Costs need a key that covers the whole workspace, or a full sign-in (lizard login).`
+        : "Billing is only visible to the workspace owner.", 2);
     }
     throw e;
   }

package/src/commands/s3.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { createHash, createHmac } from "node:crypto";
 import chalk from "chalk";
 import { Command } from "commander";
 import { api, getBaseURL, withScope, APIError, type ResourceScope } from "../lib/api.js";
@@ -12,6 +13,41 @@ interface AddonLite {
   name: string;
   type?: string;
   status?: string;
+  connection?: { endpoint?: string; accessKeyId?: string; secretKey?: string; region?: string } | null;
+}
+
+const rfc3986 = (v: string) => encodeURIComponent(v).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+const sha256hex = (v: string) => createHash("sha256").update(v).digest("hex");
+const hmac = (key: Buffer | string, v: string) => createHmac("sha256", key).update(v).digest();
+
+/**
+ * A SigV4 presigned GET for one object (path style, the way the S3 gateway expects it).
+ * The link works for `expiresIn` seconds without any credentials, so it is safe to hand
+ * to someone who must not get the addon's keys.
+ */
+export function presignGet(o: {
+  endpoint: string; accessKeyId: string; secretKey: string; region: string;
+  bucket: string; key: string; expiresIn: number; now?: Date;
+}): string {
+  const base = new URL(o.endpoint);
+  const segments = [...base.pathname.split("/").filter(Boolean), o.bucket, ...o.key.split("/")];
+  const canonicalUri = "/" + segments.map(rfc3986).join("/");
+  const iso = (o.now ?? new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+  const date = iso.slice(0, 8);
+  const scope = `${date}/${o.region}/s3/aws4_request`;
+  const query: Record<string, string> = {
+    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
+    "X-Amz-Credential": `${o.accessKeyId}/${scope}`,
+    "X-Amz-Date": iso,
+    "X-Amz-Expires": String(o.expiresIn),
+    "X-Amz-SignedHeaders": "host",
+  };
+  const canonicalQuery = Object.keys(query).sort().map((k) => `${rfc3986(k)}=${rfc3986(query[k])}`).join("&");
+  const canonicalRequest = ["GET", canonicalUri, canonicalQuery, `host:${base.host}\n`, "host", "UNSIGNED-PAYLOAD"].join("\n");
+  const toSign = ["AWS4-HMAC-SHA256", iso, scope, sha256hex(canonicalRequest)].join("\n");
+  const key = hmac(hmac(hmac(hmac("AWS4" + o.secretKey, date), o.region), "s3"), "aws4_request");
+  const signature = createHmac("sha256", key).update(toSign).digest("hex");
+  return `${base.protocol}//${base.host}${canonicalUri}?${canonicalQuery}&X-Amz-Signature=${signature}`;
 }
 
 interface ServicesResponse {
@@ -177,6 +213,35 @@ export function registerS3(program: Command) {
       }
     });
 
+  s3.command("url")
+    .description("Print a temporary download link for an object (works without credentials until it expires)")
+    .argument("<key>", "Object key, e.g. report.txt")
+    .option("--addon <name>", "S3 addon name or ID (default: the project's only S3 addon)")
+    .option("--bucket <name>", "Bucket", "default")
+    .option("--expires <seconds>", "How long the link works, in seconds (max 604800 = 7 days)", "3600")
+    .option("-p, --project <id>", "Project name, slug, or ID")
+    .action(async (key: string, opts) => {
+      const expiresIn = Number(opts.expires);
+      if (!Number.isInteger(expiresIn) || expiresIn < 1 || expiresIn > 604800) {
+        throw new Error(`--expires must be a whole number of seconds from 1 to 604800 (got ${opts.expires}).`);
+      }
+      const { projectId, scope } = await resolveProjectScope(opts.project);
+      const addon = await resolveS3AddonId(projectId, scope, opts.addon);
+      const data = await api.get<ServicesResponse>(withScope(`/api/projects/${projectId}/services`, scope));
+      const c = (data.addons ?? []).find((a) => a.id === addon.id)?.connection;
+      if (!c?.endpoint || !c.accessKeyId || !c.secretKey) {
+        throw new Error(`S3 addon ${addon.name} has no credentials yet; wait until it is running (lizard ps).`);
+      }
+      const url = presignGet({
+        endpoint: c.endpoint, accessKeyId: c.accessKeyId, secretKey: c.secretKey, region: c.region || "us-east-1",
+        bucket: opts.bucket, key, expiresIn,
+      });
+      const expiresAt = new Date(Date.now() + expiresIn * 1000).toISOString();
+      if (isJSONMode()) return printJSON({ url, key, bucket: opts.bucket, expiresIn, expiresAt });
+      console.log(url);
+      info(chalk.dim(`Works until ${expiresAt}. Anyone with the link can download ${key}.`));
+    });
+
   s3.command("list")
     .alias("ls")
     .description("List objects in an S3 addon bucket")