# Sandboxes quickstart

Boot a sandbox, run code in it, expose a port, and pause it with the Lizard SDK.

## Install

```bash
# JavaScript / TypeScript
npm install @lizard-build/sdk

# Python
pip install lizard-sdk
```

## Authenticate

Sandboxes authenticate with an **API key**. Create one in the dashboard (**Sandboxes → Get started → New API key**) — it's shown once, so copy it immediately.

Set it in your environment and the SDK picks it up automatically:

```bash
export LIZARD_API_KEY="<your-api-key>"
```

You can also pass it explicitly: `Sandbox.create('base', { apiKey, project })`.

## Pick a project

Every sandbox belongs to a project — usage is metered per project, so the API refuses a create without one. Name the project by its ID, slug, or name.

The `Lizard` client pins one project, so you only say it once:

```ts
import { Lizard } from '@lizard-build/sdk';

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

```python
from lizard import Lizard

lizard = Lizard(project="my-project")
sandbox = lizard.create("base")
```

`Sandbox.create` takes the same `project` option when you'd rather not hold a client. Both forms are used below.

## Your first sandbox

**JavaScript / TypeScript**

```ts
import { Sandbox } from '@lizard-build/sdk';

// Boot from a template (default: 'base') in a project
const sandbox = await Sandbox.create('base', { project: 'my-project' });

// Run a command and wait for it to finish
try {
  const result = await sandbox.process.exec('node -e "console.log(2 ** 10)"');
  console.log(result.stdout);     // 1024
  console.log(result.exitCode);   // 0
} finally {
  await sandbox.kill();
}
```

**Python**

```python
from lizard import Sandbox

sandbox = Sandbox.create("base", project="my-project")

# exec_ (trailing underscore) because `exec` is reserved in Python
try:
    result = sandbox.process.exec_("python -c 'print(2 ** 10)'")
    print(result.stdout)     # 1024
finally:
    sandbox.kill()
```

`process.exec` returns `{ stdout, stderr, exitCode }`. It waits for the command to complete — background long-running processes with a trailing `&`.

## Working with files

`sandbox.fs` reads and writes directly into the micro-VM filesystem, creating parent directories as needed.

```ts
await sandbox.fs.write('/app/server.js', `
  const http = require('http');
  http.createServer((_, res) => res.end('hello from Lizard')).listen(3000);
`);

const src = await sandbox.fs.read('/app/server.js');
const entries = await sandbox.fs.list('/app');   // [{ name, path, type, size }]
await sandbox.fs.makeDir('/app/data');
await sandbox.fs.remove('/app/old.log');
```

| Method | Description |
|---|---|
| `fs.write(path, data)` | Write a file — string or bytes; makes parent dirs |
| `fs.read(path)` | Read a file as a UTF-8 string |
| `fs.list(path)` | List directory entries |
| `fs.makeDir(path)` | Create a directory and any missing parents |
| `fs.remove(path)` | Delete a file or directory |

## Exposing a port

Start an HTTP server inside the sandbox and get a public HTTPS URL for it — no tunneling.

```ts
await sandbox.process.exec('node /app/server.js &');   // listen on :3000

const host = await sandbox.getHost(3000);
console.log(`Live at https://${host}`);
// https://<sandboxId>-3000.sandbox.<region>.onlizard.com
```

`getHost(port)` registers a route to that port and returns the hostname. The URL is public and TLS-terminated. Remove it again from the dashboard.

## Pause and resume

Pause freezes the guest vCPUs and retains its current state in host memory. It does not write a durable snapshot. Check the [pause and expiration issue](https://lizard.build/docs/platform/known-issues#sandbox-pause-and-expiration) before retaining a session beyond its original deadline.

```ts
// Set the environment up once
const sandbox = await Sandbox.create('base', { project: 'my-project' });
await sandbox.process.exec('npm install -g some-heavy-toolchain');
const id = sandbox.sandboxId;

await sandbox.pause();          // freeze the guest; see the lifecycle issue below

// …minutes or hours later, from anywhere:
const resumed = await Sandbox.connect(id);   // resumes guest state still held by the host
await resumed.process.exec('some-heavy-toolchain --version');   // already installed
await resumed.kill();
```

`Sandbox.connect(id)` resumes a paused sandbox automatically. You can also call `sandbox.resume()` on a handle you already hold.

**Python**

```python
sandbox = Sandbox.create("base", project="my-project")
sandbox.process.exec_("pip install numpy pandas")
sandbox_id = sandbox.sandbox_id
sandbox.pause()

resumed = Sandbox.connect(sandbox_id)   # resumes guest state still held by the host
resumed.process.exec_("python -c 'import numpy'")
resumed.kill()
```

## Timeouts

A sandbox with a positive timeout expires after that lifetime. The SDK defaults to five minutes; `timeoutMs: 0` at creation disables expiration. Set an explicit limit and release the sandbox when the task ends. Adjust a running sandbox with:

```ts
const sandbox = await Sandbox.create('base', { project: 'my-project', timeoutMs: 10 * 60 * 1000 }); // 10 min
await sandbox.setTimeout(30 * 60 * 1000);   // extend to 30 min from now
```

Pause is intended to freeze the remaining running time, but the current [lifecycle issue](https://lizard.build/docs/platform/known-issues#sandbox-pause-and-expiration) needs a verified backend release. Do not rely on an unlimited pause for data retention.

## Managing sandboxes

```ts
const sandbox = await Sandbox.create('base', { project: 'my-project' });
const info = await sandbox.getInfo();     // { sandboxId, template, startedAt, endAt, … }

const all = await Sandbox.list();         // every running sandbox for this account
await sandbox.kill();
```

## Full example

An agent that writes a script, runs it, serves the result, and pauses the guest for a later call:

```ts
import { Sandbox } from '@lizard-build/sdk';

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

try {
  await sandbox.fs.write('/app/app.js', `
    const http = require('http');
    http.createServer((_, res) => res.end('ok')).listen(3000);
  `);
  await sandbox.process.exec('node /app/app.js &');

  const host = await sandbox.getHost(3000);
  const res = await fetch(`https://${host}`);
  console.log(await res.text());          // ok

  await sandbox.pause();                   // resume later with Sandbox.connect(sandbox.sandboxId)
} catch (err) {
  await sandbox.kill();
  throw err;
}
```

## Next steps

- **[SDK Reference](https://lizard.build/docs/sandboxes/sdk-reference)** — every `Sandbox`, `CodeSandbox`, and `Volume` method.
- **[Code Interpreter](https://lizard.build/docs/sandboxes/code-interpreter)** — run stateful, multi-language code.
- **[Persistent Volumes](https://lizard.build/docs/sandboxes/volumes)** — attach storage that outlives a single sandbox.