# 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](https://lizard.build/docs/sandboxes/quickstart) for a walkthrough.

## Install & authenticate

```bash
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](https://lizard.build/docs/sandboxes/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). |

```ts
const lizard = new Lizard({ project: 'my-project' });
const sandbox = await lizard.create('base');
```

```python
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](#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](https://lizard.build/docs/sandboxes#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](https://lizard.build/docs/sandboxes/volumes) 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 |

```ts
const sandbox = await Sandbox.create('base', { project: 'my-project', timeoutMs: 10 * 60 * 1000 });
```

## `CodeSandbox`

Extends `Sandbox` with a stateful kernel. See [Code Interpreter](https://lizard.build/docs/sandboxes/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](https://lizard.build/docs/sandboxes/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](https://lizard.build/docs/sandboxes/quickstart) — install, authenticate, and a full walkthrough.
- [Code Interpreter](https://lizard.build/docs/sandboxes/code-interpreter) — the `CodeSandbox` guide.
- [Persistent Volumes](https://lizard.build/docs/sandboxes/volumes) — the `Volume` guide.

## Lifecycle status

Before relying on pause to retain a session beyond its original deadline, read [known issues](https://lizard.build/docs/platform/known-issues#sandbox-pause-and-expiration). Pause keeps guest state in host memory; it is not a durable backup.