# Running code

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

```ts
const result = await sandbox.run({
  code,                                  // the body of an async function
  functions,
  scope: {
    root: 'sdk',                         // name of the tree inside the code (default)
    values: { files, user },             // cloned in, exposed as `files`, `user`
    spread: false,                       // true: top-level functions also as bare identifiers
  },
  approval: { mode: 'deny' },            // see Approval
  caps: { timeoutMs: 30_000 },           // per-run override of the sandbox caps
  signal: controller.signal,             // cancel → status "aborted"
  onLog:  (line) => ui.append(line),     // console output, live
  onCall: (record) => audit.push(record) // every function call
});
```

`result.status` is one of five, and every result carries `logs`, `calls`
and `stats`:

```ts
switch (result.status) {
  case 'ok':      result.value;                       // what the code returned (undefined → null)
  case 'error':   result.error;                       // { name, message, line? } — thrown by the code or a SyntaxError
  case 'limit':   result.limit; result.error.message; // "timeout" | "busy" | "ops" | "output" | "input" | "crash"
  case 'aborted':                                     // the signal fired
  case 'pending': result.pending; result.resume;      // collect mode, see Approval
}
result.logs;   // [{ level, text, at }]
result.calls;  // [{ seq, fn, input, ok, ms, decision?, error? }]
result.stats;  // { ms, opsUsed, logsDropped }
```

Error names you can match: `SandboxUnavailable` (the frame or the worker
could not start), `ApprovalRejected`, `UnknownFunction`, `CloneError`,
`SandboxLimit`, `ReplayMismatch`, `BadDecision`, `InvalidRun`.

`toToolOutput(result)` maps a result to what a chat tool usually returns,
worded for a model:

```ts
toToolOutput(result);
// { ok: true, result, logs? }
// { ok: false, error: "TypeError: x is not a function (line 3)" }
// { ok: false, error: "Denied (sandbox_limit): more than 200 function calls in one run" }
// { ok: false, error: "Paused: 3 operations in this code need the user's approval and were NOT run. …" }
```

Runs on one sandbox are queued; create more sandboxes for parallel runs.
With `workerPerRun: true` (the default) nothing survives from one run to
the next.