Vercel Sandbox

Run coding agents in persistent Vercel sandboxes through the normalized SDK API.

Vercel provides hosted sandboxes for coding agents and persistent workspaces, with files, processes, public previews, and filesystem snapshots.

Persistence is enabled by default. Pass persistent: false to vercel() when you want an ephemeral sandbox instead.

Installation

Terminal

bun add @opencoredev/sandbox-sdk ai zod @vercel/sandbox

Use OIDC on Vercel and during local development. Run bunx vercel link, then bunx vercel env pull to write VERCEL_OIDC_TOKEN to .env.local. Deployed Vercel applications receive the token automatically.

Outside Vercel, pass an access token with its team and project:

credentials.ts

import { vercel } from "@opencoredev/sandbox-sdk/vercel";

const provider = vercel({
  token: process.env.VERCEL_TOKEN!,
  teamId: process.env.VERCEL_TEAM_ID!,
  projectId: process.env.VERCEL_PROJECT_ID!,
});

See Vercel's authentication guide for token creation and project identifiers.

Run a command

vercel.ts

import { createSandbox } from "@opencoredev/sandbox-sdk";
import { vercel } from "@opencoredev/sandbox-sdk/vercel";

await using sandbox = await createSandbox({ provider: vercel() });
const result = await sandbox.run("node --version");
console.log(result.stdout);

Run an AI SDK agent

This provider works with AI SDK ToolLoopAgent through the normalized sandbox session. Pass the language model from your existing AI SDK provider or AI Gateway setup.

sandbox-agent.ts

import { ToolLoopAgent, type LanguageModel } from "ai";import { createSandbox } from "@opencoredev/sandbox-sdk";import {  createSandboxToolApproval,  createSandboxTools,  toAISandboxSession,} from "@opencoredev/sandbox-sdk/ai";import { vercel } from "@opencoredev/sandbox-sdk/vercel";export async function runSandboxAgent(model: LanguageModel) {  await using sandbox = await createSandbox({    provider: vercel({ runtime: "node24" }),  });  const aiSandbox = toAISandboxSession(sandbox);  const agent = new ToolLoopAgent({    model,    instructions: `Work only in the provided sandbox.\n\n${aiSandbox.description}`,    tools: createSandboxTools(),    toolApproval: createSandboxToolApproval(),  });  return await agent.generate({    prompt: "Inspect the repository, run its tests, and summarize the result.",    experimental_sandbox: aiSandbox,  });}

See the AI SDK guide for approval flows, direct session access, and HarnessAgent alternatives.

Files and processes

workspace.ts

await sandbox.files.write("index.mjs", `console.log("ready")`);
const process = await sandbox.processes.start("node index.mjs");

for await (const event of process.output()) {
  console.log(event.stream, event.data);
}

Vercel supports background processes, cancellation, and separate stdout and stderr streams. Background stdin is not available through the normalized process handle.

Ports and snapshots

ports.expose() registers a missing port and returns its public vercel.run URL. Creating and deleting filesystem snapshots is normalized; creating a new sandbox from a snapshot remains on sandbox.raw.

snapshot.ts

const snapshot = await sandbox.snapshots.create({ name: "prepared" });
await sandbox.snapshots.delete(snapshot);

Options

Option	Type	Default	Behavior
`runtime`	`string`	`node24`	Selects an available Vercel runtime.
`name`	`string`	Generated	Sets the sandbox name.
`ports`	`number[]`	`[]`	Registers initial public ports.
`persistent`	`boolean`	`true`	Set to `false` for an ephemeral sandbox.
`token`	`string`	OIDC	Requires `teamId` and `projectId`.
`teamId`	`string`	OIDC	Requires `token` and `projectId`.
`projectId`	`string`	OIDC	Requires `token` and `teamId`.

Behavior

Creating a filesystem snapshot stops the current Vercel session.
Persistence is enabled by default, allowing sandboxes to resume across application processes. Set persistent: false to disable it.
PTY and native runtime controls remain available through sandbox.raw.
Preview URLs are public; do not expose a service that lacks its own authentication.