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           # Python

The 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). Everything else mirrors the JS/TS API 1:1.

`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()`	Snapshot the sandbox; expiration countdown freezes and on-demand compute drops to zero.
`sandbox.resume()`	Resume a paused sandbox in place.
`sandbox.setTimeout(ms)`	Set or extend the sandbox’s lifetime, from now.
`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'` (or a custom template)
`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
`volumeId`	string	—	Attach a volume at `/data`
`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.

Member	Description
`Volume.create(projectId, name, options)`	Create a volume. `options.sizeGb` defaults to `5`.
`Volume.list(projectId)`	List volumes in a project → `[{ id, name, sizeGb, status, attachedTo, … }]`.
`Volume.get(projectId, volumeId)`	Get a handle to an existing volume.
`volume.getInfo(projectId)`	Fetch metadata and attachment status.
`volume.delete(projectId)`	Delete a volume — it must be detached first.

SDK Reference

Install & authenticate

Lizard

Sandbox

Sandbox.create(template?, options?)

CodeSandbox

runCode(code, opts?)

Volume

See also