SDK reference
Install the Lizard SDK and create an API key in Settings → API keys. Store it in LIZARD_API_KEY. Each sandbox needs a project: pass projectId (Python: project_id) or resolve an ID, slug, or name with project.
Create options
| TypeScript | Python |
|---|---|
projectId / project | project_id / project |
timeoutMs | timeout_ms |
region | region |
volumeName / volumeId | volume_name / volume_id |
size | size |
snapshotId | snapshot_id |
apiKey | api_key |
Choose a template from the current catalog. Enabled templates include base, codex, and interpreter; availability depends on the region and pool capacity. interpreter includes Python and common data libraries. Check tool versions inside your sandbox. The public CLI does not provide a custom-template upload flow.
The SDK and CLI default to a five-minute lifetime. The raw API and dashboard default to no expiration. Set an explicit lifetime: timeoutMs: 0 at creation disables expiration; a positive value sets a deadline. setTimeout accepts 1000–2147483647 ms, not zero. Commands do not reset the deadline. This is not an idle timer.
Methods
| API (TypeScript) | Methods |
|---|---|
Sandbox.create(template, options) | Create in a project from a catalog template. |
Sandbox.connect(sandboxId) | Attach to an existing sandbox; no automatic resume. |
Sandbox.list() | List accessible sandboxes; inspect their status. |
sandbox.getInfo() | Fetch status and metadata. |
sandbox.process.exec(cmd) | Run a shell command; return stdout, stderr, and exitCode. |
sandbox.fs.write(path, data) | Write text or valid UTF-8 bytes; create parent directories. |
sandbox.fs.read(path) | Read a UTF-8 text file. |
sandbox.fs.readBytes(path) | Read bytes from a file. |
sandbox.fs.list(path) | List directory entries. |
sandbox.fs.makeDir(path) | Create a directory and missing parents. |
sandbox.fs.remove(path) | Remove a file or directory. |
sandbox.getHost(port) | Register a public HTTPS hostname for a port. |
sandbox.setTimeout(ms) | Set the remaining lifetime, at least 1000 ms. |
sandbox.pause() / sandbox.resume() | Queue a pause or resume and return at once. |
sandbox.waitForStatus(status) | Wait for paused or running; throw if the pause failed. |
sandbox.snapshot(name, { poolSize }) | Save memory and /workspace files as a private snapshot. |
Sandbox.waitForSnapshot(snapshotId) | Wait until a snapshot is ready. |
Sandbox.restore(snapshotId) | Start a new sandbox from a ready copy. |
sandbox.kill() | Stop the sandbox and detach its volume. |
Python: exec_, get_info, get_host, set_timeout, sandbox_id, read_bytes, make_dir, wait_for_status, wait_for_snapshot, pool_size.
Current runtime limits
Command results contain stdout, stderr, and the exit code. Command timeouts are limited to 1–600 seconds. The current runtime does not apply the SDK command options envs, workdir, or user; set the directory and environment in the shell command when needed. Create-time envs and metadata are also not applied.
Use fs.write for text or valid UTF-8 bytes and fs.read for text. Binary uploads are not supported by the current write endpoint. For a binary download, use fs.readBytes (Python: read_bytes).
Pass size ('small', 'medium', or 'large') to choose 2 vCPU / 4 GB, 4 vCPU / 8 GB (the default), or 8 vCPU / 16 GB; see sizes and prices. size does not apply to a sandbox restored from a snapshot. Select a region explicitly when needed; a catalog entry does not guarantee free capacity.
Unsupported APIs
sandbox.fork() and file watching return HTTP 501. Sandbox.connect does not resume a paused or stopped sandbox; call resume() on a paused one. SSH protocol access is not available; lizard sandbox ssh opens an interactive shell with your CLI credentials.
CodeSandbox, runCode / run_code, and execution-context methods remain in the SDK, but the hosted template catalog does not provide their required execution server. The legacy default code-interpreter-v1 is unavailable. Changing its name to interpreter does not enable this API. Use Sandbox.create("interpreter") and process commands as shown below.
Storage and billing
Files and running processes remain available while the sandbox runs. After it stops, only files written to an attached Persistent Volume at /workspace can be reused by a later sandbox. Without a volume, /workspace is temporary. Each volume attaches to one sandbox at a time and uses node-local storage; export files that must survive node loss.
Each size has a flat hourly price, billed by the second while the sandbox runs, idle time included. Egress is included up to 2 TB per account over a rolling 30 days. A sandbox restored from a snapshot is billed by measured usage. A paused sandbox is not billed; Persistent Volumes bill separately while you keep the data. Pause or kill a sandbox when the task ends.
Quickstart · SDK reference · Run Python · Dashboard · Persistent Volumes
Updated