@lizard-build/cli 4.0.44 → 4.0.46

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

@@ -0,0 +1,201 @@
+# Deploys in depth
+
+The details behind the deploy, database and secrets sections of the core guide: how builds are chosen, git and upload deploys, service fields, worker mode, secret precedence and references, addon variables, and multi-step recipes.
+
+## Contents
+
+- [Before you deploy](#before-you-deploy)
+- [Platform builder](#platform-builder)
+- [Deploying](#deploying)
+- [Worker mode](#worker-mode)
+- [Secrets](#secrets)
+- [Managed addons](#managed-addons)
+- [Composition patterns](#composition-patterns)
+- [Logs, metrics and lizard run](#logs-metrics-and-lizard-run)
+
+## Before you deploy
+
+This skill documents platform behavior (build pipeline, env precedence, what knobs the API exposes). It does not describe the user's repo.
+
+Before writing commands for a specific project:
+
+1. Read the user's `package.json`, `Dockerfile`, `requirements.txt`, framework config — confirm what already exists before adding flags.
+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.
+3. Ports: `lizard up` fixes a new service's port from `--port`, else the folder's Dockerfile `EXPOSE`, else 3000, and the app must listen there (`$PORT`). lizardpack's Python commands bind 8000 and PHP 80: pass `--port 8000` / `--port 80`, or a start command that reads `$PORT`. Git services take the port from the image's `EXPOSE` unless `containerPort` or a `PORT` variable is set. Nothing reads the port from logs.
+4. When in doubt, ask the user or run `lizard <cmd> --help --json`.
+
+## Platform builder
+
+Builds run on the platform's build nodes (no local Docker needed). When a build fails, read logs with `lizard logs --build`.
+
+### Build decision order
+
+1. Repo Dockerfile (verbatim) — if `dockerfilePath` (relative to `rootDirectory`) is set, the platform builds that Dockerfile unchanged and ignores `buildCommand`/`startCommand` for the image. A set `startCommand` still replaces the image's ENTRYPOINT and CMD at run time (`sh -c`, so the image needs `sh`).
+2. Synthesized Dockerfile — if `buildCommand` and/or `startCommand` are set (on the service or via `lizard up`), the platform generates a Go, Python or Node Dockerfile, chosen by the command's first word (anything else gets Node). It replaces the repo Dockerfile and lizardpack, so on other stacks fix the start through a Dockerfile, not `startCommand`.
+3. Root `Dockerfile` — used as is for uploads. For git, used unless it has no install or build `RUN` (`npm|yarn|pnpm|bun|pip|bundle|cargo|go build|mvn|gradle`) and copies a build folder (`COPY dist ...`, `build`, `out`, `.next`, `public`): then lizardpack replaces it and the build log says so.
+4. lizardpack auto-detect — Hugo, Go, Node, Python, Rust, Ruby, PHP, Java, static, first match wins. When nothing matches, the image runs `bash start.sh`, which builds but fails to start.
+
+### What triggers a rebuild
+
+- `git push` to the tracked branch → auto-rebuild, when the Lizard GitHub App covers the repo (`lizard git status --json`).
+- `lizard redeploy` / `lizard up` → explicit rebuild.
+- Setting a `VITE_*` or `NEXT_PUBLIC_*` variable → the platform redeploys the running services that receive it, so the build bakes it in. Do NOT chain a `lizard redeploy`. See [Applying an env change](#applying-an-env-change) for which builds receive them.
+- `service set` for build-affecting fields (`repoUrl`, `branch`, `sourceType`, `buildCommand`, `dockerfilePath`, `rootDirectory`) → auto-rebuilds a service whose status is `running`. Do NOT chain a `lizard redeploy` after it — that queues a second build. A service that never came up, crashed or stopped doesn't rebuild: run `lizard redeploy`.
+- `service set` for runtime-only fields (`startCommand`, `preDeployCommand`, `containerPort`, `watchPatterns`) → no auto-rebuild. Follow with `lizard redeploy` to apply.
+- All other env vars / secrets → applied without a rebuild; the service restarts to pick them up.
+
+## Deploying
+
+First question for a new service: upload vs git repo. **Always check for a git remote before reaching for `up`** — the CLI never auto-detects one, so you must do it yourself:
+
+```
+git remote get-url origin
+```
+
+- **Exit 0 with a GitHub URL → use the git-source path below**, not `up`. Parse `owner/repo` from the URL and run `lizard add -r owner/repo -n <svc>`. This is strongly preferred: pushes redeploy (with the Lizard GitHub App), and there's no re-upload on every change.
+- **No remote / non-GitHub / not a git repo → use tarball upload (`lizard up`).** This is the fallback for quick local iteration or no-remote situations, not the default.
+
+`lizard up` always works regardless of git state, which makes it the path of least resistance — resist it when a GitHub remote exists. Only fall back to upload when the remote check actually fails. (For a private repo whose remote exists but isn't yet accessible to Lizard, run `lizard git connect` to install the GitHub App, then use the git-source path — don't silently downgrade to a tarball.)
+
+### Git-source deploy (preferred when there's a remote)
+
+```
+# One-shot for a new service from GitHub (tracks main):
+lizard add -r owner/repo -n <svc> --json
+
+# Another branch:
+lizard add -r owner/repo -n <svc> --no-deploy --json
+lizard service set <svc> --set branch=<branch> --json
+lizard redeploy --service <svc> --wait --json
+
+# Existing service: switch source to git (rebuilds by itself when the service is running;
+# otherwise follow with `lizard redeploy --service <svc>`):
+lizard service set <svc> \
+  --set sourceType=github \
+  --set repoUrl=https://github.com/owner/repo \
+  --set branch=main \
+  --json
+```
+
+`add -r` with a name that already exists overwrites that service (branch back to `main`, commands cleared) and redeploys it: pick a new `-n`. A private repo Lizard can't read answers 404 `Repository not found`: `lizard git connect --json` gives an `installUrl` for the user. When `repoUrl` is set, pushes to the branch redeploy through the Lizard GitHub App. With a `rootDirectory` or watch patterns, only pushes touching either one redeploy; `autoDeploy=false` turns pushes off.
+
+Useful `service set` fields (the full list is in the plain `lizard service set --help`; the JSON schema leaves it out):
+
+- `sourceType` = `github | upload`
+- `repoUrl`, `branch`, `rootDirectory`
+- `dockerfilePath` — use a specific repo Dockerfile, bypasses lizardpack auto-detect
+- `buildCommand`
+- `startCommand`, `preDeployCommand` — `preDeployCommand` runs before `startCommand` at the start of every container (each replica, each restart), and only when `startCommand` is also set (otherwise it is skipped). If it fails, the container never starts. Make it safe to run many times and at the same time.
+- `watchPatterns` — string array, comma-separated or JSON
+- `containerPort` — TCP port the app listens on (a new `lizard up` service gets 3000 unless `--port` or an `EXPOSE` says otherwise). Set to `0` for [worker mode](#worker-mode).
+- `name` — rename a service (lowercase a-z, digits, hyphens; 1–40 chars). Goes through `config:apply`; the legacy `PATCH /api/apps/:id` returns 410. Refs to the old name (`${{old.KEY}}`) stop resolving: update them.
+
+Field names are flat and match the wire schema 1:1 (and `service show` output). No `build.*` / `deploy.*` / `source.*` grouping exists in the API, DB, or node-agent.
+
+`service set` uses optimistic concurrency via `configRevision`. On 409, re-read with `lizard service show`, reconcile, retry; `--force` overrides.
+
+### Tarball upload (no git remote, or quick local iteration)
+
+```
+lizard up --json
+```
+
+- Uploads cwd as a tarball (at most 150 MB compressed) and forces `sourceType=upload`. In a git repo it sends tracked files plus untracked files that `.gitignore` doesn't exclude; outside git it skips `node_modules`, `.git`, `dist`, `build`, `.next`, virtualenvs and caches, so a prebuilt `dist/` is not sent. There is no `.lizardignore`, and `.dockerignore` is not read.
+- Streams build logs; ends with `{ event: "deployed", status: "running", url }`. A failed build ends with `{ event: "error", message }` and exit 1; no `deployed` event means the service isn't running yet (see the core guide).
+- With no linked service, `up` deploys into the service named like `package.json` `name` (else the folder), and switches it to an upload even if it was git-backed. `--service <name>` deploys to that service, creating it when none has the name; a folder linked to an addon (after `lizard add postgres`) is treated as unlinked.
+- Flags: `--project`, `--service`, `--region`, `--build-command`, `--start-command`, `--pre-deploy-command`, `--port`, `--detach`, `--ci`.
+- If cwd isn't linked and no `--project` is given, it links the folder to the default project (see the core guide) and deploys there as a new service. `--project <name>` uses that project, or creates it if none matches. It never creates a project from the folder name on its own.
+- `lizard up` always switches the service to `sourceType=upload`. Do not use it to update a git-backed service — use `lizard redeploy` or push to the remote.
+
+## Worker mode
+
+For services that don't expose an HTTP listener (background workers, reconcilers, queue consumers, cron-style polling loops), set `containerPort=0`. The platform then:
+
+- Skips `PORT` env injection (the worker doesn't bind anywhere).
+- Runs no readiness check, and each deploy stops the old copy before starting the new one (two copies never overlap).
+- Skips `EXPOSE` in the synthesized Dockerfile.
+- A generated `.onlizard.com` domain and route may still exist; they answer with an error.
+
+Set it one of three ways:
+
+```
+lizard up --port 0                              # new upload-source worker
+lizard port 0 [--service <svc>]                 # flip existing service to worker mode, then `lizard redeploy`
+lizard service set <svc> --set containerPort=0  # same, via the config:apply path
+```
+
+`lizard port` with no argument prints the current port (or `worker mode` when 0). Worker mode is a hard switch — re-deploys are needed for the port change to take effect.
+
+Don't use worker mode for a regular HTTP service that just happens to be slow to start — worker mode hides "the listener never came up" bugs because there's nothing to check.
+
+## Secrets
+
+Two scopes exist. No workspace-level globals.
+
+- Project ("global"): `lizard secrets set KEY=v [K2=v2 …] --global` → project scope (wire: `secrets.shared`)
+- Service (default): `lizard secrets set KEY=v [K2=v2 …] [--service <svc>]` → service scope (wire: `secrets.services[<svc>]`)
+
+`set` is variadic. Companion subcommands: `lizard secrets list|delete K1 K2|import` (import reads dotenv from stdin). When the linked service in cwd is set, plain `lizard secrets set KEY=v` writes to that service. Pass `--global` to escape to project scope.
+
+### Precedence (last writer wins)
+
+```
+addon-issued env  <  project secrets  <  project env  <  app env  <  app secrets  <  platform vars
+```
+
+App secrets override project secrets. Platform vars come last and cannot be shadowed: `PORT` (absent in worker mode), `LIZARD_PROJECT_ID`, `LIZARD_SERVICE_NAME` (an internal `app-…` handle, not the dashboard name), `LIZARD_PUBLIC_DOMAIN` (absent until the service has a domain; a comma list once a custom domain is attached) and `LIZARD_PRIVATE_DOMAIN`. For service-to-service URLs use `${{<svc>.LIZARD_PRIVATE_DOMAIN}}`, not the service name. A `PORT` you set yourself doesn't override the injected one, but it becomes `containerPort` at the next deploy when the port wasn't set explicitly. Addon-issued env is every running Postgres and Redis addon's public `DATABASE_URL` / `REDIS_URL`, injected into every service at its next deploy or secret change; with two addons of a type, either may win.
+
+### Secret scoping
+
+Default to service-scope. `--global` puts the value into `process.env` of every service in the project — including ones that don't need it.
+
+Rules:
+
+- Check first: `lizard secrets list` (+ `--global`) before set/update — avoid creating a duplicate or shadowing an existing key (service scope wins over global; see [Precedence](#precedence-last-writer-wins)).
+- Default — service-scope: `lizard secrets set KEY=v --service <svc>` per consumer. For addon DSNs, prefer a private reference when the consumer can reach it: `lizard secrets set DATABASE_URL='${{postgres.DATABASE_PRIVATE_URL}}' --service <svc>` (no separate `env` command — refs are interpolated wherever they appear). Refs are read again on every deploy, redeploy and secret change, not on `lizard restart`; there is no automatic credential rotation. A ref to another service sees only its stored values and platform vars, not the `DATABASE_URL` it got automatically.
+- `secrets import` keeps quotes and `export ` prefixes as part of the value: strip them first.
+- `--global` only for non-secrets and provably-public values: `LOG_LEVEL`, `NODE_ENV`, feature flags, frontend `SENTRY_DSN`. If unsure whether a value is a secret, treat it as one. A compromised service reads its own env; broader scope = more credentials exposed for no reason.
+
+### Applying an env change
+
+- Runtime vars/secrets apply without rebuilding the image. The application process restarts to read its new environment; do not promise uninterrupted requests.
+- `VITE_*` / `NEXT_PUBLIC_*` (build-time baked) → setting one redeploys the running services that receive it; a plain restart won't pick them up. Only some builds bake them in: lizardpack or a reused repo Dockerfile on a GitHub service, or a Node-style build generated from `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.
+
+## 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.
+
+- `postgres` — two connection URLs: prefer `DATABASE_PRIVATE_URL` when available and reachable within the same project and region (no ingress/egress charges); use `DATABASE_URL` for public access, such as local clients or external CI (network charges may apply). Private URLs resolve only in the addon's region, and `lizard add` defaults to `us-east-1`. Also exposes `PGHOST`, `PGPORT` (the public endpoint), `PGUSER`, `PGPASSWORD`, `PGDATABASE`, `POSTGRES_USER`, `POSTGRES_DB`, `POSTGRES_PASSWORD`.
+- `redis` — `REDIS_URL`; services in the same project should use `REDIS_PRIVATE_URL`. No eviction policy and no append-only file are configured: if it runs out of memory, the instance restarts and recent writes can be lost. Keep data you cannot lose in Postgres.
+- `s3` — `S3_ENDPOINT`, `S3_DEFAULT_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_REGION`. Auto-creates a private bucket named `default`; each S3 addon stores up to 16 GiB. Make a bucket public from the dashboard's S3 browser; objects in a public bucket are served without auth two ways: the gateway URL the dashboard shows, `https://s3-<region>.onlizard.com/<addonId>/<bucket>/<key>`, or the platform proxy `<dashboard-host>/api/s3/<addonId>/public/<bucket>/<key>` (the host `lizard open` launches; long-lived immutable cache headers). For AWS SDK use, set `forcePathStyle: true`. ACL flips aren't on the CLI yet, so point users at the dashboard. To push a local file into a bucket directly (no AWS SDK needed), use `lizard s3 upload <file> [--addon <name>] [--bucket <name>] [--key <key>] [--content-type <type>]` — auto-resolves the project's only S3 addon and bucket `default` if omitted; prints `{key, etag, size, url}` (`url` is `null` unless the bucket is public). `lizard s3 list|ls [--bucket <name>] [--prefix <p>]` lists objects in a bucket. `lizard s3 url <key> [--expires <seconds>]` prints a presigned link (default 1 hour, at most 7 days) that downloads a private object without credentials. The CLI has no ACL command: make a bucket public in the dashboard, or with an S3 `PutBucketAcl` (`public-read`) call using the addon's credentials.
+
+## Composition patterns
+
+Multi-step requests follow natural chains. Return one unified response, don't farm out steps:
+
+- First deploy from git — pick action via the setup decision flow in the core guide → `lizard add -r owner/repo` → stream build → surface URL.
+- First deploy from local code — Setup decision flow → `lizard up` → surface URL.
+- Add a managed database to an existing service — `lizard add postgres` → bind the consumer's `DATABASE_URL` to the private reference as described above (the service restarts with it; no redeploy needed).
+- Keep files across deploys — `lizard volume create data --service <svc> --mount-path /data` (one volume per service; the service restarts with it) → point the app's file paths there.
+- Add object storage to a service — `lizard add s3` → reference `${{s3.S3_ENDPOINT}}`, `${{s3.S3_DEFAULT_BUCKET}}`, `${{s3.S3_ACCESS_KEY_ID}}`, `${{s3.S3_SECRET_ACCESS_KEY}}`, `${{s3.S3_REGION}}` from the consumer service. The `default` bucket is private; to serve files without auth, have the user make it public in the dashboard's S3 browser, then objects are served at `<dashboard-host>/api/s3/<addonId>/public/default/<key>`. See [Managed addons](#managed-addons).
+- Wire a fresh git source on an existing service — `service set --set sourceType=github --set repoUrl=… --set branch=…` (rebuilds a running service by itself; otherwise `redeploy`).
+- Fix a failed build — `logs --build --service <svc>` → diagnose → fix project (user's repo) OR adjust `buildCommand` / `startCommand` via `service set` → `redeploy --service <svc> --wait` → `logs` to verify.
+- Fix a crash-looping service — `logs --restart latest --service <svc>` → fix the cause (secret, port, code) → `redeploy --service <svc> --wait`: a service whose first deploy failed gets its URL only from a successful deploy.
+- Add a custom domain — `domain <host> --service <svc>` (the hostname is a positional, there is no `add` subcommand) → give the user `dnsRecords` → `domain verify <host> --service <svc>` once DNS propagates (it checks only the TXT; nothing verifies on its own). `domain list --service <svc>` shows pending domains. If the host is already attached to another of the user's services, the attach 409s with a reclaim hint — re-run with `--force` to move it here.
+
+## Logs, metrics and lizard run
+
+`lizard metrics --all` ignores the directory's linked service for this command.
+It uses the linked project unless `--project <name>` selects another project.
+Without `--all`, metrics defaults to the linked service, or the project overview
+when no service is linked. Do not combine `--all` with `--service`.
+The project overview includes `Egress` (outbound bytes per second) and `Volumes`
+(used / total bytes). These columns use the latest sample from the past hour;
+`Sampled` refers to CPU and memory. Missing measurements show `—`.
+Watch mode refreshes CPU and memory every 3 seconds and I/O history every 30 seconds.
+JSON output includes the history in each service's `series` and `timestamps` fields.
+
+`lizard run --service <app>` injects stored values only: `${{…}}` refs arrive as literal text, and platform vars (`PORT`, `LIZARD_*`) are not set. `--service <addon>` injects the addon's real connection values, so use it to run a local command against a database. To check a service's wiring, use `lizard logs --build --service <svc>` (it warns about every reference that came back empty), `lizard secrets list --service <svc> --json` (names) and `lizard secrets list --ref --service <svc> --json` (the references that resolve; `available: false` for an addon that isn't running); shell access into services is off.
+
+For exact flags, `lizard <cmd> --help --json`. Other commands not shown above: `lizard git` (GitHub integration), `lizard config` (project configuration), `lizard workspace` (workspace info) — discover each with `lizard <cmd> --help --json`.

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

@@ -0,0 +1,169 @@
+# Sandboxes in depth
+
+The details behind the Sandboxes section of the core guide. Read the part the task needs.
+
+## Contents
+
+- [Templates](#templates)
+- [Running commands](#running-commands)
+- [Files](#files)
+- [Ports](#ports)
+- [Lifetime](#lifetime)
+- [Size and pricing](#size-and-pricing)
+- [Interactive shell](#interactive-shell)
+- [Coding agents](#coding-agents)
+- [Desktop (computer use)](#desktop-computer-use)
+- [Volumes](#volumes)
+- [Snapshots and pause/resume](#snapshots-and-pauseresume)
+
+## Templates
+
+| `-t` | What is inside |
+|---|---|
+| `base` (default) | Python 3.11 on Alpine Linux, nothing else |
+| `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) |
+
+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 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
+
+```
+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>
+```
+
+`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> --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` 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
+
+`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, 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; 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
+
+`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 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" --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. 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.
+
+## 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 (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
+
+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; 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. 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

@@ -0,0 +1,227 @@
+# Building with Lizard (Lizard SDK)
+
+Use Lizard SDK when the user's own code creates and drives sandboxes or manages Lizard resources: an agent framework, a code-execution feature, a backend that gives each of its users a machine. For one-off work from a terminal, use the CLI instead.
+
+## Contents
+
+- [Install and configure](#install-and-configure)
+- [Quickstart](#quickstart)
+- [Commands and output](#commands-and-output)
+- [Files](#files)
+- [Stateful code (CodeSandbox)](#stateful-code-codesandbox)
+- [Ports](#ports)
+- [Keep files (volumes)](#keep-files-volumes)
+- [Lifecycle, pause, snapshots and fork](#lifecycle-pause-snapshots-and-fork)
+- [Desktop (computer use)](#desktop-computer-use)
+- [Sandboxes for your own users](#sandboxes-for-your-own-users)
+- [Platform APIs](#platform-apis)
+- [Billing from code](#billing-from-code)
+- [Errors](#errors)
+
+## Install and configure
+
+| SDK | Install | Requires |
+|---|---|---|
+| TypeScript | `npm install @lizard-build/sdk` | Node.js 18.16+ |
+| Python | `pip install lizard-sdk` | Python 3.10+ |
+
+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.
+
+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 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` | 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.
+
+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
+
+```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)
+```
+
+Always kill the sandbox when done: `try/finally` in TypeScript, the `with` block in Python.
+
+## Commands and output
+
+`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, **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` (`mod_time` in Python). Reads stop at 15 MB (HTTP 413). File watching is not available yet.
+
+## Stateful code (CodeSandbox)
+
+`CodeSandbox` boots the `interpreter` template and runs Python in a persistent Jupyter kernel, so variables, imports and functions survive between calls. Plain `process.exec` starts a new process each time.
+
+```ts
+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('int(df.x.sum())')
+  const out = run.results[0]
+  if (out?.type === 'result') console.log(out.data)   // "6"
+} finally {
+  await sandbox.kill()
+}
+```
+
+```python
+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("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` 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
+
+Start the server on `0.0.0.0` inside the sandbox, then publish the port:
+
+```ts
+const { hostname, url, accessToken } = await sandbox.exposePort(3000)
+const res = await fetch(`https://${hostname}/api`, { headers: { 'X-Lizard-Access-Token': accessToken } })
+await sandbox.unexpose(3000)
+```
+
+```python
+exposed = sandbox.expose_port(3000)
+res = httpx.get(f"https://{exposed.hostname}/api", headers={"X-Lizard-Access-Token": exposed.access_token})
+sandbox.unexpose(3000)
+```
+
+The port is private: every request needs the token in the `X-Lizard-Access-Token` header, or once as `?lizard_token=<token>` in a browser, which then keeps a cookie. `url` already carries the token, so treat it like a password. `getHost(port)` / `get_host(port)` returns only the hostname, without a scheme.
+
+## Keep files (volumes)
+
+Only files on an attached volume outlive the sandbox; volumes mount at `/workspace`. A volume attaches to one sandbox at a time, and the sandbox runs in the volume's region, so omit `region` when attaching one.
+
+```ts
+await lizard.volumes.getOrCreate('agent-files', { sizeGb: 10 })
+const sandbox = await lizard.create('base', { volumeName: 'agent-files' })
+```
+
+```python
+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). Grow one with `lizard.volumes.resize('agent-files', 20)` / `lizard.volumes.resize("agent-files", 20)`; volumes only grow.
+
+## Lifecycle, pause, snapshots and fork
+
+| Task | TypeScript | Python |
+|---|---|---|
+| Reconnect by ID | `Sandbox.connect(id)` | `Sandbox.connect(id)` |
+| Status | `sandbox.getInfo()` | `sandbox.get_info()` |
+| New lifetime from now (1000–2147483647 ms) | `sandbox.setTimeout(ms)` | `sandbox.set_timeout(ms)` |
+| List a project's sandboxes | `Sandbox.list({ projectId })` | `Sandbox.list(project_id=...)` |
+| Kill | `sandbox.kill()` | `sandbox.kill()` |
+| 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 (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.
+
+## Desktop (computer use)
+
+The `desktop` template has a graphical desktop with Chromium on `DISPLAY=:1`. `sandbox.desktop.start({ width, height })` starts it and returns `url` (watch and control) and `viewOnlyUrl` (watch only). Both are credentials: never log them, and share `viewOnlyUrl` when someone only needs to look. Then drive it with `screenshot()` (PNG bytes), `click(x, y)`, `moveMouse`, `drag`, `type(text)`, `press('ctrl+l')`, `scroll(direction)` and `openUrl(url)`. Input never goes through a shell. On other templates these calls fail with `DESKTOP_NOT_SUPPORTED`.
+
+## Sandboxes for your own users
+
+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' })
+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 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")
+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)
+```
+
+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
+
+The same client manages the rest of Lizard: `projects`, `services` (deploy, inspect, scale, run commands), `addons` (managed databases), `secrets`, `domains`, `storage` (S3 objects), `github`, `metrics`, `workspaces`, `apiKeys` / `api_keys`, `regions`, `billing` and `volumes`. `whoami()` returns the identity behind the key. `platform` is the raw HTTP client for endpoints without a method. A config change that saved but failed to deploy raises `ConfigApplyError`: read its `result` before retrying.
+
+## Billing from code
+
+`billing.subscription()` returns the plan, trial and this month's usage; `billing.startCheckout()` / `start_checkout()` returns a Stripe Checkout URL for the trial or Pro, which the user finishes in a browser. `startProNow`, `cancel` and `resume` change what the account pays: call them only when the account owner asks.
+
+## Errors
+
+| 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, 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 |
+| `LizardError` | Other API failures, including unsupported operations |
+
+Each error has the HTTP `status` (`status_code` in Python) and, when the API sends one, a `code`. `kill()` returns `false` for a sandbox that is already gone. Check command exit codes and code errors separately from API errors.
+
+Full reference: [sandboxes](https://github.com/lizard-build/lizard-sdk/blob/main/docs/sandboxes.md), [platform](https://github.com/lizard-build/lizard-sdk/blob/main/docs/platform.md), [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).