# API reference

> @faustine-ai/browser-sandbox documentation · https://browser-sandbox.faustine.ai/docs/api-reference/ · source: README.md on GitHub (https://github.com/faustine-ai/browser-sandbox)

## `createSandbox(options): Sandbox`

| Option | Type | Default | |
|---|---|---|---|
| `frame` | `{ url: string }` \| `{ srcdoc: true }` | required | Where the frame document comes from. |
| `caps` | `Partial<Caps>` | see [Limits](https://browser-sandbox.faustine.ai/docs/limits.md) | Defaults for every run. |
| `warm` | `boolean` | `false` | Boot the frame now instead of on the first run. |
| `workerPerRun` | `boolean` | `true` | A fresh worker per run; `false` reuses one. |
| `bootTimeoutMs` | `number` | `10000` | Handshake and spawn timeout before `SandboxUnavailable`. |
| `container` | `Element` | `document.body` | Where the frame element is appended. |

`Sandbox`: `state` (`idle` \| `booting` \| `ready` \| `failed` \| `disposed`),
`ready: Promise<void>` (rejects with `SandboxUnavailable`), `run(options):
Promise<RunResult>`, `dispose()`.

## `sandbox.run(options): Promise<RunResult>`

| Option | Type | |
|---|---|---|
| `code` | `string` | The body of an async function. |
| `functions` | `FunctionMap` | From `defineFunctions` / `fromObject`. |
| `scope.root` | `string` | Name of the tree. Default `sdk`. |
| `scope.values` | `Record<string, unknown>` | Cloned in, exposed by name. Keys must be identifiers; `console` and the root name are reserved. |
| `scope.spread` | `boolean` | Also expose top-level functions as bare identifiers. |
| `approval` | `{ mode: 'deny' }` \| `{ mode: 'pause', onApproval }` \| `{ mode: 'collect', onApproval? }` | Default `deny`. |
| `caps` | `Partial<Caps>` | Per-run override. |
| `signal` | `AbortSignal` | Cancel. |
| `onLog` | `(line: LogLine) => void` | Console output, live. |
| `onCall` | `(record: CallRecord) => void` | Every call, after it was answered. |

`RunResult` is the union in [Running code](https://browser-sandbox.faustine.ai/docs/running-code.md).

## Functions

- `defineFunctions(defs)`: `Record<string, FunctionImpl | FunctionEntry>` → frozen `FunctionMap`.
  `FunctionEntry = { call, approval?, positional?, description?, input? }`.
- `fromObject(object, { names, approval?, descriptions?, extra? })`.
- `isFunctionName(name)`.
- `describe(functions, { root?, format?: 'index' | 'ts' })`.

## Output

- `toToolOutput(result)` → `{ ok: true, result, logs? } | { ok: false, error, logs? }`.

## Frame (`@faustine-ai/browser-sandbox/frame`, also on the main entry)

- `frameDocument()`: the HTML.
- `frameHeaders()`: the headers to serve it with.
- `FRAME_CSP`, `FRAME_PROTOCOL_VERSION`, `frameVersion()`.

## Adapters

- `/ai`: `runCodeTool(options)`, `clientTools(map, options?)`, `fromTools(tools, options?)`.
- `/codemode`: `asExecutor(sandbox, options?)`, `toExecuteResult(result)`.
- `/tanstack`: `asIsolateDriver(sandbox, options?)`, `toExecutionResult(result)`.

## Types

`Caps`, `SandboxOptions`, `RunOptions`, `RunResult`, `LogLine`, `CallRecord`,
`PendingCall`, `Decisions`, `ApprovalOptions`, `OnCallApproval`,
`OnBatchApproval`, `LimitKind`, `FunctionMap`, `FunctionEntry`,
`SandboxError` (with `name: SandboxErrorName`).