SDK Reference
The @lizard-build/sdk (JS/TS) and lizard-sdk (Python) packages are what most agents, apps, and scripts use to drive sandboxes. This page catalogs every class and method; see the Quickstart for a walkthrough.
Install & authenticate
npm install @lizard-build/sdk # JavaScript / TypeScript
pip install lizard-sdk # PythonThe SDK reads LIZARD_API_KEY from the environment, or accepts an explicit apiKey option on Sandbox.create / Sandbox.connect. See Quickstart → Authenticate for how to create a key.
Every sandbox also belongs to a project — usage is metered per project, so a create without one is refused.
Lizard
A client pinned to one project, so you name the project once instead of on every call.
| Member | Description |
|---|---|
new Lizard({ project, apiKey?, apiUrl?, timeoutMs? }) | Create a client. project is required — its ID, slug, or name (Lizard(project=…) in Python). |
lizard.create(template?, options?) | Boot a sandbox in the client’s project. |
lizard.connect(sandboxId) | Attach to a sandbox by ID, auto-resuming it if paused. |
lizard.list() | List every running sandbox for the account. |
lizard.projectId() | Resolve the client’s project reference to its ID (cached after the first call). |
const lizard = new Lizard({ project: 'my-project' });
const sandbox = await lizard.create('base');lizard = Lizard(project="my-project")
sandbox = lizard.create("base")A project reference that matches nothing the key can reach raises before any sandbox is booted, listing the projects it can see.
Python method names with a trailing underscore (
exec_) avoid shadowing reserved words, and properties are snake_case (sandbox_id) instead of camelCase (sandboxId). The examples below use JS/TS names; check the installed Python package for method signatures.
Sandbox
| Member | Description |
|---|---|
Sandbox.create(template?, options?) | Boot a sandbox. template defaults to 'base'; options.project names the project to bill. |
Sandbox.connect(sandboxId) | Attach to a sandbox by ID, auto-resuming it if paused. |
Sandbox.list() | List every running sandbox for the account. |
sandbox.sandboxId | The sandbox’s ID (sandbox_id in Python). |
sandbox.process.exec(cmd) | Run a command and wait for it to finish (process.exec_ in Python). Returns { stdout, stderr, exitCode }. |
sandbox.fs.write(path, data) | Write a file — string or bytes; creates parent directories. |
sandbox.fs.read(path) | Read a file as a UTF-8 string. |
sandbox.fs.list(path) | List directory entries → [{ name, path, type, size }]. |
sandbox.fs.makeDir(path) | Create a directory and any missing parents. |
sandbox.fs.remove(path) | Delete a file or directory. |
sandbox.getHost(port) | Register a route to port and return its public, TLS-terminated hostname. |
sandbox.pause() | Stop guest vCPUs and retain state in host memory. See lifecycle status before relying on a pause beyond the original deadline. |
sandbox.resume() | Resume a paused sandbox in place. |
sandbox.setTimeout(ms) | Set a running sandbox’s remaining lifetime in milliseconds (minimum 1000). |
sandbox.getInfo() | Fetch metadata → { sandboxId, template, startedAt, endAt, … }. |
sandbox.kill() | Terminate the sandbox immediately and free its resources. |
Sandbox.create(template?, options?)
| Option | Type | Default | Notes |
|---|---|---|---|
template | string | 'base' | 'base' or 'code-interpreter-v1' — the two supported templates |
project | string | — | Required. The project to bill — its ID, slug, or name (project in Python). Not needed via a Lizard client. |
projectId | string | — | Exact project ID; skips resolving project |
timeoutMs | int | SDK default 5 min | Lifetime in ms |
region | string | auto | Pin to a region |
volumeName | string | — | Attach a named volume from the same project at /workspace (volume_name in Python) |
volumeId | string | — | Existing ID-based callers remain supported (volume_id in Python) |
apiKey | string | LIZARD_API_KEY env var | Explicit API key, overrides the environment |
const sandbox = await Sandbox.create('base', { project: 'my-project', timeoutMs: 10 * 60 * 1000 });CodeSandbox
Extends Sandbox with a stateful kernel. See Code Interpreter for the full walkthrough.
| Member | Description |
|---|---|
CodeSandbox.create(options?) | Boot a code interpreter (defaults to the code-interpreter-v1 template). Takes the same project option as Sandbox.create. |
CodeSandbox.connect(sandboxId) | Attach to (and auto-resume) an existing code interpreter sandbox. |
sandbox.runCode(code, opts?) | Execute code in the kernel. Returns an Execution. |
sandbox.createContext(opts) | Create an isolated namespace — { language }. |
sandbox.listContexts() | List the sandbox’s contexts. |
sandbox.restartContext(context) | Clear all variables/state in a context. |
sandbox.deleteContext(context) | Free a context’s resources. |
runCode(code, opts?)
| Option | Description |
|---|---|
language | Runtime for a one-off call — 'python' (default), 'javascript', or 'bash'. Mutually exclusive with context. |
context | Run inside a specific isolated context instead of the default one. Mutually exclusive with language. |
onStdout / onStderr | Stream output line-by-line as it’s produced. |
onResult | Called for each rich result (values, generated images/charts). |
onError | Called with an ExecutionError if the code throws. |
Returns an Execution:
| Field | Description |
|---|---|
stdout / stderr | Captured output streams |
results | Rich results (values, and any generated images / charts) |
error | An ExecutionError (name, message, traceback) if the code threw |
executionCount | Monotonic counter for the kernel |
Volume
See Persistent Volumes for the full walkthrough. Names are unique per project and use lowercase letters, digits and dashes, up to 64 characters.
New volumes accept whole GB from 1 to 50, default 5 (sizeGb in TypeScript, size_gb in Python). The server config can change the maximum. Existing larger volumes keep their size; getOrCreate returns them unchanged.
| Member | Description |
|---|---|
Volume.create(projectId, name, options) | Create a volume; conflict if the name is taken. options.sizeGb defaults to 5. |
Volume.getOrCreate(projectId, name, options) | Reuse a volume or create it. Never resizes an existing volume. Python: Volume.get_or_create. |
Volume.list(projectId) | List volumes in a project → [{ id, name, sizeGb, status, attachedTo, … }]. |
Volume.get(projectId, nameOrId) | Get a volume by name or ID. |
Volume.delete(projectId, nameOrId) | Delete by name or ID after detaching. Python: Volume.remove. |
volume.getInfo(projectId) | Fetch metadata and attachment status. |
volume.delete(projectId) | Delete a volume — it must be detached first. |
See also
- Quickstart — install, authenticate, and a full walkthrough.
- Code Interpreter — the
CodeSandboxguide. - Persistent Volumes — the
Volumeguide.
Lifecycle status
Before relying on pause to retain a session beyond its original deadline, read known issues. Pause keeps guest state in host memory; it is not a durable backup.
Updated