> ## Documentation Index
> Fetch the complete documentation index at: https://boxrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the Vercel AI SDK

> Use a BoxRouter sandbox as the sandbox provider for a Vercel AI SDK harness.

`@boxrouter/ai-sdk-sandbox` lets a Vercel AI SDK harness run its shell and file tools in a BoxRouter sandbox. Each session is one sandbox, and BoxRouter picks the route. `@ai-sdk/harness` is experimental, so test and pin it together with `@boxrouter/ai-sdk-sandbox`.

**Before You Begin:** A BoxRouter API key, a connected provider key or Credits, and Node.js 22.18 or later.

## Install

The package installs the BoxRouter TypeScript SDK as a dependency.

```bash theme={"theme":"css-variables"}
npm install @boxrouter/ai-sdk-sandbox
```

## Open a Session

Set `BOXROUTER_API_KEY` and `BOXROUTER_BASE_URL` as in the [quickstart](https://boxrouter.ai/docs/quickstart.md#set-your-api-key). This script calls the sandbox provider directly, so it needs no model key. Save it as `sandbox.mjs`:

```js theme={"theme":"css-variables"}
import { randomUUID } from "node:crypto";
import { createBoxRouterSandbox } from "@boxrouter/ai-sdk-sandbox";

const runLabel = `ai-sdk-${randomUUID()}`;
console.log("Run label:", runLabel);
const provider = createBoxRouterSandbox({
  timeoutSeconds: 300,
  labels: { run: runLabel },
});
const sandbox = await provider.createSession();
try {
  const result = await sandbox.run({
    command: "printf 'hello from AI SDK sandbox\\n'",
  });
  if (result.exitCode !== 0) throw new Error(result.stderr);
  process.stdout.write(result.stdout);
} finally {
  await sandbox.destroy();
}
```

```bash theme={"theme":"css-variables"}
node sandbox.mjs
```

Output

```text theme={"theme":"css-variables"}
Run label: <RUN_LABEL>
hello from AI SDK sandbox
```

`finally` requests sandbox destruction even when the command fails, and `destroy()` treats an already-deleted sandbox as done. If your process dies first, the sandbox can run past the end of its `timeoutSeconds` lifetime: 300 here, 1800 when unset. Use the printed run label to [find it](https://boxrouter.ai/docs/reference/list-sandboxes.md), then [destroy it](https://boxrouter.ai/docs/sandboxes.md#destroy-it).

In a harness, pass `provider` as the harness's sandbox provider; the [AI SDK harness package](https://github.com/vercel/ai/tree/main/packages/harness) documents the option. Only that model-driven run needs a model key.

## Pause Instead of Destroy

By default `stop()` destroys the sandbox. With `persistent: true`, `stop()` pauses it instead, and `resumeSession` can reattach later.

A persistent session adds the `pause_resume` requirement at creation, so only routes that can pause qualify. If none can, creation fails with `no_eligible_route`.

## Ports and Limits

* Declaring `ports` names the `previews` requirement, so only routes that grant previews qualify. Ports are fixed when the session is created; `setPorts` is not implemented.
* `setNetworkPolicy` and request transformations are not implemented.
* A request to create a sandbox that fails with an unclear error may still have made one. Use the printed run label with [List sandboxes](https://boxrouter.ai/docs/reference/list-sandboxes.md) before retrying.

[Sandboxes](https://boxrouter.ai/docs/sandboxes.md#what-you-ask-for-and-what-boxrouter-decides) explains `requirements` and the refusal you get when none is met.

## Next Steps

> [card] [Pause, Resume, and Extend](https://boxrouter.ai/docs/pause-resume.md)
>
> What persistent sessions rely on.

> [card] [Connect to a Sandbox](https://boxrouter.ai/docs/connect.md)
>
> How previews behind ports work.

> [card] [Run Commands](https://boxrouter.ai/docs/commands.md)
>
> Exit codes, timeouts, and output limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.