Use the Vercel AI SDK

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

npm install @boxrouter/ai-sdk-sandbox

Open a Session

Set BOXROUTER_API_KEY and BOXROUTER_BASE_URL as in the quickstart. This script calls the sandbox provider directly, so it needs no model key. Save it as sandbox.mjs:

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();
}

node sandbox.mjs

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, then destroy it. In a harness, pass provider as the harness’s sandbox provider; the AI SDK harness package 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 before retrying.

Sandboxes explains requirements and the refusal you get when none is met.

Next Steps

Pause, Resume, and Extend

What persistent sessions rely on.

Connect to a Sandbox

How previews behind ports work.

Run Commands

Exit codes, timeouts, and output limits.

Launch an Agent

Integrations