Using TanStack AI with Vercel Sandbox

Coding agents run shell commands, edit files, and install packages, which makes running them directly on your host machine a risk. Vercel Sandbox isolates each agent run in a managed microVM with its own filesystem, so the agent can work freely without touching your infrastructure. TanStack AI connects to it through the @tanstack/ai-sandbox-vercel provider, which plugs Vercel Sandbox into TanStack AI's provider-agnostic sandbox system.

Copy link to headingOverview

In this guide, you'll learn how to:

• Install and authenticate the @tanstack/ai-sandbox-vercel provider
• Define a sandbox with a workspace and policy
• Run a coding agent inside a Vercel Sandbox microVM
• Resume a sandbox and expose ports for previews

Copy link to headingPrerequisites

Before you begin, make sure you have:

• A Vercel account
• A TanStack AI project with @tanstack/ai installed
• A harness adapter for the agent you want to run, such as @tanstack/ai-grok-build or @tanstack/ai-claude-code

For local development, you also need Node.js 22+ and the Vercel CLI.

Copy link to headingHow it works

TanStack AI splits sandboxed agent runs into two parts. The provider owns the isolation primitive, meaning where the agent runs, and the harness is which agent runs there, such as Grok Build, Claude Code, Codex, or OpenCode. Every provider implements the same SandboxProvider contract, so your workspace and policy definitions stay the same when you swap providers.

The Vercel provider runs each sandbox as a managed Vercel Sandbox microVM. It supports persistent resume-by-id with a durable filesystem, and exposed-port domains for previewing whatever the agent builds.

Copy link to headingSteps

Copy link to heading1. Install the packages

Install the sandbox core and the Vercel provider:

pnpm i @tanstack/ai-sandbox @tanstack/ai-sandbox-vercel

npm i @tanstack/ai-sandbox @tanstack/ai-sandbox-vercel

yarn add @tanstack/ai-sandbox @tanstack/ai-sandbox-vercel

bun add @tanstack/ai-sandbox @tanstack/ai-sandbox-vercel

Copy link to heading2. Authenticate with Vercel

The provider needs a Vercel access token plus a team and project to scope sandbox usage to. Set three environment variables:

VERCEL_TOKEN=your_access_token_here
VERCEL_TEAM_ID=your_team_id_here
VERCEL_PROJECT_ID=your_project_id_here

To find these values:

1. Create an access token under account settings in the Vercel dashboard, scoped to the team that will run sandboxes.
2. Copy your team ID from your team settings.
3. Copy your project ID from the project's general settings.

Credentials for the harness itself, such as the agent's API key, don't go in these variables. Inject them as workspace secrets instead, which the provider passes into the microVM at create and resume time.

Copy link to heading3. Define the sandbox

Create the provider with vercelSandbox, then wire it into a sandbox definition:

import {
  defineSandbox,
  defineSandboxPolicy,
  defineWorkspace,
  githubRepo,
} from "@tanstack/ai-sandbox"
import { vercelSandbox } from "@tanstack/ai-sandbox-vercel"

const sandbox = defineSandbox({
  id: "vercel-agent",
  provider: vercelSandbox({ runtime: "node24" }),
  workspace: defineWorkspace({
    source: githubRepo({ repo: "owner/app" }),
    setup: ["pnpm install"],
  }),
  policy: defineSandboxPolicy({
    default: "allow",
  }),
})

The sandbox definition has three parts:

• Provider: vercelSandbox creates the managed microVM the agent runs in. The runtime option selects the runtime environment, such as node24.
• Workspace: The source clones the repository into the microVM, and setup commands run before the agent starts. This is also where you inject harness credentials as workspace secrets, which the provider passes into the microVM at create and resume time.
• Policy: The default: "allow" policy keeps headless harnesses like Grok Build and Codex on auto-approve, with the microVM boundary providing the isolation. Use Claude Code as the harness when you need command-level deny rules.

Copy link to heading4. Run an agent in the sandbox

Pass the sandbox definition to chat through the withSandbox middleware:

import { chat } from "@tanstack/ai"
import { grokBuildText } from "@tanstack/ai-grok-build"
import { withSandbox } from "@tanstack/ai-sandbox"

const stream = chat({
  adapter: grokBuildText("grok-build"),
  messages: [{ role: "user", content: "List the project files." }],
  middleware: [withSandbox(sandbox)],
})

The agent's commands now execute inside the Vercel Sandbox microVM instead of on your machine, against the cloned workspace.

Copy link to headingResume and previews

Vercel Sandbox gives the provider a durable filesystem, so a sandbox resumes by id with its files intact instead of re-cloning and re-running setup on every run.

When the agent starts a dev server, the provider exposes the port on a public domain so you can preview the result in a browser. Because the session cap resets on each resume, a sandbox's total lifetime is effectively unbounded.

Copy link to headingLimitations

• Bridged tools need a tunnel in local development. The sandbox is a remote VM, so a tool bridged from chat() can't reach your laptop's localhost. Tunnel the bridge during local development, for example with ngrok. A deployed orchestrator is reachable without a tunnel.
• No writable stdin. Spawned processes in a Vercel Sandbox don't accept host stdin, so stdin-fed harnesses write the prompt to a file and redirect it in the shell. TanStack AI handles this automatically.
• Cancel destroys the sandbox. The provider can't signal a running agent process, so cancelling a run tears down the sandbox rather than stopping the process.
• Session duration is capped. Single uninterrupted session runs for up to 24 hours on Pro and Enterprise plans and 45 minutes on Hobby, with a default timeout of 5 minutes. The cap applies per session and resets each time a sandbox stops and resumes.

Copy link to headingNext steps

• Learn about images, persistence, and more in the Vercel Sandbox documentation
• Explore workspaces, policies, and harnesses in the TanStack AI sandbox docs
• Route the same app's model calls through one API key with Vercel AI Gateway
• Use vercelGatewayDecider from TanStack AI’s Vercel AI Gateway adapter with Jev in Moderate product reviews with Jev, TanStack AI, and AI Gateway to get typed choices, scores, and boolean probabilities instead of generated text
• Build a Jev agent with TanStack Start and TanStack AI