@lizard-build/cli 4.0.41 → 4.0.43

package/skill-data/core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lizard-core
-description: "Core Lizard CLI usage guide. Read this before running any lizard commands. Covers the full app lifecycle (login, init, link, add, up, redeploy, logs, events, status, scale, restart, secrets, domains, run, metrics, billing and 402 payment errors), the workspace → project → service model, managed addons (postgres, redis, s3 with a private default bucket), the build pipeline (lizardpack auto-detect, repo Dockerfile, synthesized Dockerfile), secrets scoping and env precedence, custom domains, worker mode (containerPort=0 for non-HTTP background workloads), and runtime command discovery via `lizard <cmd> --help --json`. Use when the user asks to deploy, host, or ship an app, agent, worker, or managed database (any language, e.g. 'deploy this', 'ship it somewhere', 'host app'), mentions Lizard or `lizard <cmd>`, asks where to host a greenfield repo with no chosen platform, or asks for a managed postgres/redis/s3 without naming a host. Default for ambiguous deploy/host/ship requests; skip when the user is already in another platform's context or explicitly names a competitor."
+description: "Deploys and manages apps on Lizard with the `lizard` CLI: services from a repo or a local folder, managed databases (Postgres, Redis, S3-compatible storage), builds, secrets and environment variables, custom domains, logs, scaling and restarts, worker services, and billing. Use when the user asks to deploy, host or ship an app, agent, worker or database, mentions `lizard up`, `lizard add` or other deploy commands, or has a new repo with no chosen platform. For sandboxes, read `lizard skills get sandbox` instead."
 argument-hint: "[optional natural-language request]"
 allowed-tools: Bash(lizard:*), Bash(~/.lizard/bin/lizard:*), Bash(which:*), Bash(command:*), Bash(npm install:*)
 ---
@@ -9,6 +9,8 @@ allowed-tools: Bash(lizard:*), Bash(~/.lizard/bin/lizard:*), Bash(which:*), Bash
 
 Lizard is a unified cloud for apps, services, agents, and managed databases. All capabilities are exposed through the `lizard` CLI (npm package `@lizard-build/cli`). This skill teaches you to drive it. If `lizard` isn't on PATH, install it: `curl -fsSL https://lizard.build/install.sh | bash` on macOS and Linux (no Node.js or sudo needed; if `lizard` is still not found, call `~/.lizard/bin/lizard`), `irm https://lizard.build/api/cli/install.ps1 | iex` in Windows PowerShell, or `npm install -g @lizard-build/cli` anywhere. The install script ends by running `lizard login`, so its output may already hold the sign-in links: see [Sign-in](#sign-in).
 
+This guide covers deploys: services, managed databases, builds, secrets and domains. **Sandboxes** (create, run code, files, ports, snapshots, desktop, coding agents, Lizard SDK) have their own guide: run `lizard skills get sandbox --json` for any sandbox task.
+
 If `$ARGUMENTS` is non-empty, treat it as the user's request and act on it. If empty, ask what they want to do on Lizard.
 
 ## Read this first
@@ -21,13 +23,11 @@ Before writing commands for a specific project:
 2. Don't assume scripts/conventions that aren't visible. On the lizardpack auto-detect path, `Procfile` (`web:` line, Python/Ruby) and `package.json scripts.start` (Node) ARE picked up as the start command; on the synthesized-Dockerfile path (`buildCommand`/`startCommand` set) neither is read. Ports are inferred only from `EXPOSE`, framework defaults, or an explicit `PORT` env.
 3. When in doubt, ask the user or run `lizard <cmd> --help --json`.
 
-## Execution rules
+<!-- include: _shared/basics.md -->
+
+## Deploy command output
 
-1. Prefer the `lizard` CLI. For anything not exposed by it, ask the user — don't hit the API directly.
-2. Always pass `--json` on non-interactive calls. The CLI also auto-switches when stdout isn't a TTY. For streaming commands (`lizard up` without `--detach`), `--json` produces one JSON event per line: `{ event: "log", line }`, terminating with `{ event: "done" }` / `{ event: "error", message }`; `up` additionally emits a final `{ event: "deployed" | "failed" | "deploying", status, url }` (`url` may be `null`). `lizard logs --json` is **not** a stream: it returns the last 200 lines (override with `--tail N`, max 1000) and exits — do not wait on it expecting more. Need a specific incident? Use `--restart latest` or `--restart <id>`. Only stream logs without `--json` if the user actively wants a live tail.
-3. For unfamiliar commands, run `lizard <cmd> --help --json` first — never guess flag shapes. See [Discovery](#discovery).
-4. Resolve context before any mutation. `lizard status` shows the cwd link; `lizard ps --json` shows services in the linked project. Confirm you're targeting the right thing.
-5. For destructive actions (delete service, drop addon, overwrite a project-wide secret, prod restart), confirm intent with the user before executing. The CLI's own prompts fire only on TTY.
+For streaming commands (`lizard up` without `--detach`), `--json` produces one JSON event per line: `{ event: "log", line }`, terminating with `{ event: "done" }` / `{ event: "error", message }`; `up` additionally emits a final `{ event: "deployed" | "failed" | "deploying", status, url }` (`url` may be `null`). `lizard logs --json` is **not** a stream: it returns the last 200 lines (override with `--tail N`, max 1000) and exits — do not wait on it expecting more. Need a specific incident? Use `--restart latest` or `--restart <id>`. Only stream logs without `--json` if the user actively wants a live tail.
 
 ## Mental model
 
@@ -41,36 +41,6 @@ workspace → project → service (+ managed addons)
 - Managed addons — `postgres`, `redis`, `s3`. Provisioned with `lizard add <type>`; `s3` ships with a private bucket named `default`. See [Managed addons](#managed-addons) for the env vars each type exposes.
 - Cross-resource refs — `${{<name>.<KEY>}}` resolves at deploy time against the target's merged env. A ref to a missing target or key resolves to an empty string and does NOT fail the deploy (only circular refs throw). After wiring refs, deploy and check `lizard logs --build --service <svc>`: the build log warns about every reference that came back empty. `lizard secrets list --service <svc> --show` shows what is stored. Refs match the target's current name, so renaming the target breaks them: update them after a rename.
 
-## Discovery
-
-The CLI has ~30 subcommands. Discover at runtime:
-
-```
-lizard --help --json                       # root + all commands + global flags + exit codes
-lizard <cmd> --help --json                  # specific command schema
-lizard <cmd> <sub> --help --json            # nested (e.g. `lizard service set --help --json`)
-```
-
-Returns `{ cli, version, command: { arguments, options, subcommands }, globalOptions, exitCodes }`.
-
-## Sign-in
-
-Every command that needs an account checks the sign-in first. Without one, in JSON mode it fails with exit code `2` and `error.code: "NOT_AUTHENTICATED"`, and `error.body.login` holds what you need to get the user signed in. `lizard login --json` prints the same object at the top level. It never waits and never opens a browser:
-
-- `status: "pending"`: `authUrls` holds one link per sign-in method (`github`, `google`), and `authUrl` the one to use when only one applies. Ask the user how they sign in to Lizard and give them that link as a clickable URL. Someone with an account must use the same method as before: another method opens a second, empty account unless both share a verified email. Once they say the browser shows "CLI authorized", run the same command again (`nextCommand` when present); it picks the sign-in up. A link lasts 5 minutes; the next run prints a new one. Follow `instruction`.
-- `status: "complete"` (from `lizard login` only): `username`, `email`, `source` (`browser`, `saved`, or `env` for `LIZARD_TOKEN` / `LIZARD_API_KEY`), `account` with the plan's `state` (`trial_available`, `subscription_required`, `trialing`, `active`, `past_due`, `credits`, `enterprise`, `not_owner`, `checkout_unavailable`, `unknown`), `billingUrl`, `payUrl` when a payment failed, and an `instruction` that says what to offer and what not to touch, plus `next` commands.
-
-Never start a plan (`lizard billing start`) unless the user agrees. `lizard login` is safe to re-run: a signed-in machine skips straight to the plan. In CI nothing can be opened, so set `LIZARD_TOKEN` or `LIZARD_API_KEY`, or save a token on the machine with `printf '%s' "$TOKEN" | lizard login --token-stdin`. `lizard login --token <token>` works too, but the token lands in the process list and the shell history.
-
-## Exit codes
-
-- `0` success — continue
-- `1` generic error — inspect message, surface to user
-- `2` auth (401/403) — not signed in: give the user the link from `error.body.login` and run the command again once they have signed in (see [Sign-in](#sign-in)). No links in the body (CI, or the platform could not be reached)? Run `lizard login --json`, or ask for `LIZARD_TOKEN`.
-- `3` not found (404) — wrong name / resource gone; verify with `lizard project list` / `lizard ps`
-- `4` timeout — retry or report
-- `5` cancelled by user — stop
-
 ## Setup decision flow
 
 When the user wants to deploy or set up something new, work out the right action from cwd context before running anything:
@@ -80,14 +50,6 @@ When the user wants to deploy or set up something new, work out the right action
 3. Not linked but parent dir is linked? → likely a monorepo sub-app. Add a service in the parent's project and set `rootDirectory` to the cwd subpath via `service set`.
 4. Neither linked? → check `lizard project list --json` for one matching the directory or repo name. Match → `lizard link --project <name> [--workspace <ws>]` (pass `--workspace` to disambiguate same-named projects across workspaces). No match → `lizard up` deploys into the [default project](#default-project); run `lizard init --name <name>` first only when the user wants a separate project.
 
-## Default project
-
-A command that works on a project takes it from `--project`, then from the folder's link, then falls back to the account's **default project**: the oldest live project in the personal workspace, which every account gets at sign-up (`<username>'s Project`). So `lizard sandbox create`, `lizard up`, `lizard logs` and the rest work in a folder that was never linked. They say so on stderr: `Project: <name> (your default)`.
-
-- `lizard sandbox create` with no project lets the platform pick the default; its JSON carries `projectId`, `projectName` and `projectDefaulted: true`.
-- `lizard up` links the unlinked folder to the default project first, then creates a service named after the folder, so the next `up` from that folder updates the same service. `lizard init --force` relinks it elsewhere.
-- No default project (every project deleted): the old `No project linked. Run lizard init or pass --project <id>.` error.
-
 Naming heuristic: app-style names (`my-api`, `worker`, `flappy-bird`) are service names. Use the repo or directory name for the project.
 
 ## Platform builder
@@ -220,96 +182,6 @@ Rules:
 - `VITE_*` / `NEXT_PUBLIC_*` (build-time baked) → setting one redeploys the running services that receive it; a plain restart won't pick them up. Only a Dockerfile the platform generates bakes them in: lizardpack on a GitHub service, or a service with `buildCommand`/`startCommand`. A `dockerfilePath` build, or a `lizard up` upload without those overrides, gets no Lizard variables at build time, and no build gets build args except `COMMIT_SHA`. For public values there, commit them in `.env.production`, set a build command, or write them into the Dockerfile.
 - Verify a non-secret value or the application's behavior. Do not print the full environment: it can expose credentials.
 
-## Sandboxes: size and pricing
-
-`lizard sandbox create -s/--size small|medium|large` picks the machine; the default is `medium`. There are exactly three sizes:
-
-| Size | vCPU | RAM | Disk | Price |
-|---|---|---|---|---|
-| `small` | 2 | 4 GiB | 5 GB | $0.0162/h |
-| `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](#sandboxes-private-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: volumes
-
-Use `lizard volume create <name> --size <gb> --project <project>` for persistent sandbox storage. Names are unique within a project; use lowercase letters, digits and dashes (up to 64 characters). Pass the name to `lizard sandbox create --volume <name>`. New volumes default to 5 GB and allow 1–50 GB. The CLI reads the server's current size limits before creating a volume; a server config override may change the maximum. Existing larger volumes keep their size. Storage charges cover used bytes, not the whole allocation.
-
-## Sandboxes: timeout
-
-`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](#sandboxes-private-snapshots-and-pauseresume)). The CLI has no sandbox fork command. Use volumes for persistent files.
-
-## Sandboxes: built-in coding agents
-
-Run a coding agent inside a sandbox (use `-t codex`) on the user's own credentials:
-
-- `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 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.
-
-Use `sandbox exec` to read a log file written by your process.
-
-## Sandboxes: interactive shell
-
-`lizard sandbox ssh <id>` (alias `shell`) opens an interactive shell in any running sandbox,
-in `/workspace` as root. It uses your Lizard login, so there are no SSH keys to set up; a
-scoped API key only reaches sandboxes in its scope. It needs a real terminal — from a script
-or an agent, use `lizard sandbox exec <id> -- <cmd>` instead, which returns output and an
-exit code.
-
-## Sandboxes: Desktop (computer use)
-
-The `desktop` template is a sandbox with a graphical desktop (Openbox + Chromium) streamed to a browser over WebRTC (H.264), falling back to noVNC where WebRTC cannot connect. The viewer's side panel has fullscreen with keyboard lock, send-keys, type-clipboard and a switch to VNC.
-
-```
-lizard sandbox create -t desktop                          # only this template has a desktop
-lizard sandbox desktop <id> --open                        # start it (idempotent) and open it in the browser
-lizard sandbox desktop <id> --resolution 1920x1080        # 640-3840 x 480-2160
-lizard sandbox desktop <id> --view-only                   # watch-only link
-lizard sandbox desktop <id> --status                      # URLs/state without starting
-lizard sandbox desktop <id> --stop                        # stop and unpublish
-lizard sandbox vnc <id>                                   # native VNC app: tunnels localhost:5900 to the desktop
-lizard sandbox vnc <id> --open                            # macOS: opens Screen Sharing; --view-only, --port N
-```
-
-The printed URLs embed secrets (the desktop's token and its password): the main URL grants control of the sandbox, so treat it like a password and don't paste it into logs, issues or chat; share `--view-only` for watching. On any other template the command fails with `DESKTOP_NOT_SUPPORTED`.
-
-Agents drive the desktop from inside the sandbox once it is started (`DISPLAY=:1` is preset in the image):
-
-```
-lizard sandbox exec <id> -- xdotool mousemove 400 300 click 1
-lizard sandbox exec <id> -- xdotool type 'hello'
-lizard sandbox exec <id> -- lizard-desktop screenshot | grep -E '^[A-Za-z0-9+/=]+$' | base64 -d > screen.png
-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.
-
-## Volumes
-
-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 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
-```
-
-`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.
-
 ## Managed addons
 
 Provision with `lizard add <type>`. Each addon exposes a fixed env-var set; reference by name from a consumer service via `${{<addon-name>.KEY}}`. The first addon of a given type gets the bare type as its name (so use `postgres` in the reference for the first Managed Postgres instance); subsequent ones get `{type}-{adjective}-{noun}` like `postgres-autumn-bear`. There's no type-alias fallback — a ref must use the addon's actual name. Refs match the addon's current name, so renaming it breaks existing refs: update them after a rename. Every running Postgres and Redis addon's `DATABASE_URL` / `REDIS_URL` also reaches every service in the project at the lowest precedence; a value set on the consumer overrides it.
@@ -392,58 +264,3 @@ Skip command-by-command transcripts unless they explain a failure.
 4. A Dockerfile that copies pre-built artifacts (`COPY dist/`, `build/`, `out/`, `.next/`, `public/`) without a `RUN` build step gets silently regenerated by lizardpack. Add a build step or set `dockerfilePath` to force verbatim use.
 5. Don't generate Dockerfiles unsolicited — lizardpack auto-detects most stacks. Try a deploy first; write one only if it fails. Ask before either.
 6. Don't put runtime secrets (DB credentials, API keys, RPC creds, S3 keys) in `--global` "just in case another service needs it later". Scope to the services that consume them — see [Secret scoping](#secret-scoping).
-
-## Billing
-
-Billing belongs to the account; these commands take no project or service selector.
-
-```sh
-lizard billing --json              # plan, trial, this month's usage, next charge, billingUrl
-lizard billing start --json        # Stripe Checkout link: the Pro trial, or Pro at once
-lizard billing promo <code> --json # a longer trial with more trial usage
-lizard billing open                # the Billing page
-lizard metrics --cost --json       # spend per project; proCredits for Pro accounts
-```
-
-Pro costs $19/month, taxes included, and includes $19 of usage each month for
-everything on the account; unused usage does not carry over. Usage above that is
-pay as you go at the published rates, charged to the card as it builds up. A new
-account starts with no plan. The 7-day trial includes $5 of usage; Checkout asks
-for a card and charges nothing until the trial ends, then Pro is $19/month. When
-the trial usage runs out, running resources pause and nothing new can be created
-until Pro starts. Data is kept. Promo codes work only before the first payment.
-Trial accounts run 1 replica per app and 5 sandboxes at once; after the first
-paid invoice, 5 replicas per app and 100 sandboxes (paused sandboxes don't
-count). Pro cards are changed or removed on the Billing page;
-`lizard billing payment-methods remove` works only for Enterprise accounts.
-Enterprise accounts pay as you go, invoiced monthly. There are no top-ups, no
-auto top-up and no crypto or x402 payments.
-
-When the account needs a plan or a payment, every create command (`up`, `add`,
-`sandbox create`, `volume create`, `domain`, redeploys) fails with HTTP 402.
-The JSON error has `code: "PAYMENT_REQUIRED"` (`"INSUFFICIENT_CREDITS"` from
-older servers), a `message` to show the user as is (its last line is the link),
-and `body.status` with the links:
-
-| `body.status` | What to offer |
-|---|---|
-| `trial_available` | Start the trial: `body.subscribeUrl`, or `lizard billing start` |
-| `subscription_required` | The trial is used: Start Pro ($19 today) the same way |
-| `trial_credits_used` | Trial usage is used up: Start Pro now with `lizard billing start-now` or in Billing |
-| `past_due` | A payment failed: pay the open invoice in Billing (`body.billingUrl`) |
-| `paused` | Running resources are paused, data kept. `message` says why: trial usage used up (Start Pro now, as above) or a failed payment (pay the open invoice in Billing) |
-| anything else | Show `message` and `body.billingUrl` |
-
-Checkout and invoice pages open in the user's browser; you cannot finish them.
-Give the user the link, never ask for card details in chat, and retry the
-failed command after they say they are done. `start-now` (charges $19 now),
-`cancel` and `resume` change what the user pays: run them only when the user
-asks. Without a terminal, `start-now` and `cancel` need `-y`.
-
-## Sandboxes: private 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 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/sandbox/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: lizard-sandbox
+description: "Creates and manages Lizard sandboxes with the `lizard` CLI and Lizard SDK: a cloud sandbox (a Firecracker microVM) to run commands and code, copy files in and out, expose ports over HTTPS, open a shell, run Claude Code or Codex, drive a desktop and browser for computer use, keep files on volumes, and pause, snapshot or restore. Use for any sandbox task: an isolated sandbox, cloud machine or code interpreter, running untrusted or AI-generated code, or giving an agent its own computer."
+argument-hint: "[optional natural-language request]"
+allowed-tools: Bash(lizard:*), Bash(~/.lizard/bin/lizard:*), Bash(which:*), Bash(command:*), Bash(npm install:*)
+---
+
+# Lizard sandboxes
+
+A sandbox is a Linux machine for running code and agents: a Firecracker microVM with its own kernel. It lives 5 minutes by default and is then deleted with its files. If `lizard` isn't on PATH, install it: `curl -fsSL https://lizard.build/install.sh | bash` on macOS and Linux (if `lizard` is still not found, call `~/.lizard/bin/lizard`), or `npm install -g @lizard-build/cli` on Windows. The install script ends by signing in: see [Sign-in](#sign-in).
+
+If `$ARGUMENTS` is non-empty, treat it as the user's request and act on it. If empty, ask what they want to run.
+
+## Sandbox or deploy?
+
+- **Sandbox:** run code, tests, a build or an agent on demand, for minutes or hours, then delete it or snapshot it. The place for untrusted or AI-generated code.
+- **Deploy** (`lizard up`): a service that keeps running and serves traffic at a stable URL, with managed databases next to it. For that, run `lizard skills get core --json`.
+
+## Quickstart
+
+```
+lizard sandbox create --json                              # base template, medium size, 5-minute lifetime; the JSON has the id
+lizard sandbox exec <id> -- python3 -c 'print(2 ** 10)'   # exits with the command's exit code
+lizard sandbox files put <id> ./app.py /workspace/app.py
+lizard sandbox exec <id> -- python3 /workspace/app.py
+lizard sandbox expose <id> 8000 --json                    # an HTTPS URL for a port in the sandbox
+lizard sandbox timeout <id> 3600000                       # keep it for an hour from now
+lizard sandbox rm <id> -y                                 # delete it now
+```
+
+`lizard sandbox list --json` shows the project's sandboxes; `--all` shows every one you have.
+
+## Templates
+
+| `-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) |
+
+The platform validates the name; `lizard sandbox create --help --json` lists the templates this CLI knows.
+
+## 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.
+
+## Files
+
+```
+lizard sandbox files ls <id> [path]              # default /
+lizard sandbox files cat <id> <path>
+lizard sandbox files put <id> <local> <remote>
+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.
+
+## 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.
+
+## 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.
+
+## Size and pricing
+
+`lizard sandbox create -s/--size small|medium|large` picks the machine; the default is `medium`. There are exactly three sizes:
+
+| Size | vCPU | RAM | Disk | Price |
+|---|---|---|---|---|
+| `small` | 2 | 4 GiB | 5 GB | $0.0162/h |
+| `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)).
+
+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.
+
+## Interactive shell
+
+`lizard sandbox ssh <id>` (alias `shell`) opens an interactive shell in any running sandbox,
+in `/workspace` as root. It uses your Lizard login, so there are no SSH keys to set up; a
+scoped API key only reaches sandboxes in its scope. It needs a real terminal — from a script
+or an agent, use `lizard sandbox exec <id> -- <cmd>` instead, which returns output and an
+exit code.
+
+## Coding agents
+
+Run a coding agent inside a sandbox (use `-t codex`) on the user's own credentials:
+
+- `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 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.
+
+Use `sandbox exec` to read a log file written by your process.
+
+## Desktop (computer use)
+
+The `desktop` template is a sandbox with a graphical desktop (Openbox + Chromium) streamed to a browser over WebRTC (H.264), falling back to noVNC where WebRTC cannot connect. The viewer's side panel has fullscreen with keyboard lock, send-keys, type-clipboard and a switch to VNC.
+
+```
+lizard sandbox create -t desktop                          # only this template has a desktop
+lizard sandbox desktop <id> --open                        # start it (idempotent) and open it in the browser
+lizard sandbox desktop <id> --resolution 1920x1080        # 640-3840 x 480-2160
+lizard sandbox desktop <id> --view-only                   # watch-only link
+lizard sandbox desktop <id> --status                      # URLs/state without starting
+lizard sandbox desktop <id> --stop                        # stop and unpublish
+lizard sandbox vnc <id>                                   # native VNC app: tunnels localhost:5900 to the desktop
+lizard sandbox vnc <id> --open                            # macOS: opens Screen Sharing; --view-only, --port N
+```
+
+The printed URLs embed secrets (the desktop's token and its password): the main URL grants control of the sandbox, so treat it like a password and don't paste it into logs, issues or chat; share `--view-only` for watching. On any other template the command fails with `DESKTOP_NOT_SUPPORTED`.
+
+Agents drive the desktop from inside the sandbox once it is started (`DISPLAY=:1` is preset in the image):
+
+```
+lizard sandbox exec <id> -- xdotool mousemove 400 300 click 1
+lizard sandbox exec <id> -- xdotool type 'hello'
+lizard sandbox exec <id> -- lizard-desktop screenshot | grep -E '^[A-Za-z0-9+/=]+$' | base64 -d > screen.png
+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.
+
+## Volumes
+
+Use `lizard volume create <name> --size <gb> --project <project>` for persistent sandbox storage. Names are unique within a project; use lowercase letters, digits and dashes (up to 64 characters). Pass the name to `lizard sandbox create --volume <name>`. New volumes default to 5 GB and allow 1–50 GB. The CLI reads the server's current size limits before creating a volume; a server config override may change the maximum. Existing larger volumes keep their size. Storage charges cover used bytes, not the whole allocation.
+
+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 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
+```
+
+`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 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.
+
+## From code: Lizard SDK
+
+For an app or script that creates sandboxes itself, use Lizard SDK instead of calling the CLI:
+
+| SDK | Install | Requires |
+|---|---|---|
+| TypeScript | `npm install @lizard-build/sdk` | Node.js 18+ |
+| Python | `pip install lizard-sdk` | Python 3.10+ |
+
+The SDK reads `LIZARD_API_KEY`. Create one with `lizard keys create <name> --project <project> --json`: a key limited to one project is safest when the code runs somewhere else.
+
+```ts
+import { Lizard } from '@lizard-build/sdk'
+
+const lizard = new Lizard({ project: 'my-project' })
+const sandbox = await lizard.create('base', { timeoutMs: 300_000 })
+try {
+  await sandbox.fs.write('/tmp/hello.txt', 'Hello from Lizard!')
+  const result = await sandbox.process.exec('cat /tmp/hello.txt')
+  if (result.exitCode !== 0) throw new Error(result.stderr)
+  console.log(result.stdout)
+} finally {
+  await sandbox.kill()
+}
+```
+
+```python
+from lizard import Lizard
+
+lizard = Lizard(project="my-project")
+with lizard.create("base", timeout_ms=300_000) as sandbox:
+    sandbox.fs.write("/tmp/hello.txt", "Hello from Lizard!")
+    result = sandbox.process.exec_("cat /tmp/hello.txt")
+    if result.exit_code != 0:
+        raise RuntimeError(result.stderr)
+    print(result.stdout)
+```
+
+Guides: [TypeScript](https://github.com/lizard-build/lizard-sdk/blob/main/packages/js/README.md), [Python](https://github.com/lizard-build/lizard-sdk/blob/main/packages/python/README.md), [sandbox reference](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md).
+
+<!-- include: _shared/basics.md -->

package/src/commands/add.ts

@@ -80,7 +80,7 @@ interface Project {
  * When `workspaceFlag` is provided, the lookup is constrained to that
  * workspace — useful for disambiguating identically-named projects.
  */
-async function resolveProject(
+export async function resolveProject(
   flagValue: string | undefined,
   workspaceFlag?: string,
 ): Promise<string> {
@@ -117,6 +117,14 @@ async function resolveProject(
   const link = getProjectLink();
   if (link?.projectId) return link.projectId;
 
+  // Not linked: the account's default project, as every other command does.
+  const { defaultProject, noteDefaultProject } = await import("../lib/default-project.js");
+  const fallback = await defaultProject();
+  if (fallback) {
+    noteDefaultProject(fallback.name);
+    return fallback.id;
+  }
+
   throw new Error(
     "No project linked to this directory. Run `lizard link --project <name>` to use an existing project, or `lizard init --name <name>` to create one.",
   );

package/src/commands/login.ts

@@ -116,6 +116,13 @@ export function nextSteps(linked: boolean): Array<{ command: string; why: string
         ". It is deleted with its files after 5 minutes unless `--timeout` says otherwise (`--timeout 0`: no limit). " +
         "Then `lizard sandbox ssh <id>` for a shell, or `lizard sandbox exec <id> -- <cmd>` to run a command.",
     },
+    {
+      command: "lizard add postgres redis s3",
+      why:
+        "Managed Postgres, Managed Redis and S3-compatible Managed Object Storage in one command, in the same project " +
+        "(the default project when the folder is not linked). Every service there gets DATABASE_URL and REDIS_URL; " +
+        "other keys by reference, e.g. `${{postgres.DATABASE_PRIVATE_URL}}`.",
+    },
     {
       command: "lizard up",
       why: linked
@@ -133,7 +140,8 @@ export function nextStepsNote(): string {
     ["lizard sandbox ssh <id>", "Open a shell in it"],
     ["lizard sandbox exec <id> -- <cmd>", "Run a command in it"],
     ["lizard sandbox list", "See your sandboxes"],
-    ["lizard up", "Or deploy this folder"],
+    ["lizard add postgres redis s3", "Add Postgres, Redis and object storage"],
+    ["lizard up", "Deploy this folder"],
   ];
   const width = Math.max(...rows.map(([cmd]) => cmd.length)) + 3;
   return rows.map(([cmd, why]) => chalk.cyan(cmd) + " ".repeat(width - cmd.length) + why).join("\n");

package/src/commands/skill.ts

@@ -18,12 +18,26 @@ interface Source {
   pathOf(name?: string): string;
 }
 
+/** Inline `<!-- include: _shared/x.md -->` lines, as scripts/gen-skills.mjs does for the embedded copy. */
+export function expandIncludes(md: string, root: string): string {
+  return md.replace(/^<!-- include: ([\w./-]+) -->$/gm, (line, rel: string) => {
+    const file = path.resolve(root, rel);
+    if (!file.startsWith(path.resolve(root) + path.sep)) return line;
+    try {
+      return readFileSync(file, "utf8").trimEnd();
+    } catch {
+      return line;
+    }
+  });
+}
+
 function fsSource(dir: string): Source {
   return {
     list: () => {
       try {
         return readdirSync(dir)
           .filter((name) => {
+            if (name.startsWith("_")) return false;
             try {
               return statSync(path.join(dir, name)).isDirectory();
             } catch {
@@ -37,7 +51,7 @@ function fsSource(dir: string): Source {
     },
     read: (name) => {
       try {
-        return readFileSync(path.join(dir, name, "SKILL.md"), "utf8");
+        return expandIncludes(readFileSync(path.join(dir, name, "SKILL.md"), "utf8"), dir);
       } catch {
         return null;
       }

package/src/index.ts

@@ -6,6 +6,7 @@ import { setJSONMode, isJSONMode, error } from "./lib/format.js";
 import { requireAuth, isLoggedIn } from "./lib/auth.js";
 import { setBaseURL, setAccessToken, APIError, isProjectDeletedError, isAccountScopeError } from "./lib/api.js";
 import { checkForUpdateInBackground, runBackgroundUpdate, CURRENT_VERSION } from "./lib/updater.js";
+import { skillFor } from "./lib/skill-route.js";
 
 const BANNER = chalk.rgb(16, 185, 129)(
   [
@@ -27,34 +28,34 @@ const BANNER = chalk.rgb(16, 185, 129)(
 // of guessing commands from flag docs alone.
 const AGENTS_HELP = [
   chalk.bold("Start here (for AI agents):"),
-  "  " + chalk.cyan("lizard skills get core"),
+  "  " + chalk.cyan("lizard skills get sandbox") + chalk.dim("   sandboxes: run code, files, ports, snapshots, desktop, agents"),
+  "  " + chalk.cyan("lizard skills get core") + chalk.dim("      deploys: services, databases, builds, secrets, domains"),
   "",
   chalk.dim(
-    "  Skills ship with the CLI (always version-matched) and cover the full app",
+    "  Skills ship with the CLI (always version-matched) and come with copy-paste",
   ),
   chalk.dim(
-    "  lifecycle — deploy, link, addons, logs, scaling, secrets, domains — with",
-  ),
-  chalk.dim(
-    "  copy-paste examples. Prefer this over guessing commands from flag docs alone.",
+    "  examples. Prefer them over guessing commands from flag docs alone.",
   ),
 ].join("\n");
 
+
 // Compact form of the same pointer, shown on every subcommand's `--help` so the
 // per-command flag docs never read as the whole story. Mirrors the `agents`
 // block that `--help --json` already emits for every command; one tight line so
 // it sits above a subcommand's Usage without crowding it.
-const AGENTS_HELP_COMPACT =
+const agentsHelpCompact = (skill: string) =>
   chalk.bold("For AI agents:") +
   " run " +
-  chalk.cyan("lizard skills get core") +
+  chalk.cyan(`lizard skills get ${skill}`) +
   chalk.dim(" for version-matched usage and examples.");
 
-/** Attach the compact agents pointer to every (nested) subcommand's help. */
-function addAgentsPointerToSubcommands(cmd: Command) {
+/** Attach the compact agents pointer to every (nested) subcommand's help, naming the skill for its subtree. */
+function addAgentsPointerToSubcommands(cmd: Command, skill?: string) {
   for (const sub of cmd.commands) {
-    sub.addHelpText("before", AGENTS_HELP_COMPACT + "\n");
-    addAgentsPointerToSubcommands(sub);
+    const own = skill ?? skillFor(sub.name());
+    sub.addHelpText("before", agentsHelpCompact(own) + "\n");
+    addAgentsPointerToSubcommands(sub, own);
   }
 }
 
@@ -274,6 +275,13 @@ function findTargetCommand(
   return { target: cur, unknown: null };
 }
 
+/** The command directly under the root that `cmd` belongs to. */
+function topLevelOf(cmd: Command): Command {
+  let top = cmd;
+  while (top.parent && top.parent !== program) top = top.parent;
+  return top;
+}
+
 function dumpOption(o: any) {
   return {
     flags: o.flags,
@@ -386,8 +394,9 @@ async function main() {
       cli: "lizard",
       version: CURRENT_VERSION,
       agents: {
-        start: "lizard skills get core",
-        note: "Skills ship with this CLI version and cover the full app lifecycle (deploy, link, addons, logs, scaling, secrets, domains) with copy-paste examples. Prefer this over guessing commands from flag docs alone.",
+        start: `lizard skills get ${isRoot ? "core" : skillFor(topLevelOf(target).name())}`,
+        skills: { sandbox: "lizard skills get sandbox", core: "lizard skills get core" },
+        note: "Skills ship with this CLI version, with copy-paste examples: `sandbox` for sandboxes (run code, files, ports, snapshots, desktop, coding agents), `core` for deploys (services, databases, builds, secrets, domains). Prefer them over guessing commands from flag docs alone.",
       },
       command: dumpCommand(target),
       globalOptions: isRoot

package/src/lib/skill-route.ts

@@ -0,0 +1,7 @@
+/** Top-level commands whose work the `sandbox` skill covers; everything else is in `core` (deploys). */
+const SANDBOX_COMMANDS = new Set(["sandbox", "volume", "agents"]);
+
+/** Which embedded skill an agent should read for a top-level command. */
+export function skillFor(topLevel: string): "sandbox" | "core" {
+  return SANDBOX_COMMANDS.has(topLevel) ? "sandbox" : "core";
+}