API reference

`createSandbox(options): Sandbox`

Option	Type	Default
`frame`	`{ url: string }` \| `{ srcdoc: true }`	required	Where the frame document comes from.
`caps`	`Partial<Caps>`	see Limits	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.

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).

createSandbox(options): Sandbox

sandbox.run(options): Promise<RunResult>