Using TanStack AI with Vercel Sandbox
Run coding agents in isolated Vercel Sandbox microVMs with the @tanstack/ai-sandbox-vercel provider, with durable resume-by-id, port previews, and workspace policies.
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.
In this guide, you'll learn how to:
Prerequisites
- 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
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
How 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.
For local development, you also need Node.js 22+ and the Vercel CLI.
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.
2. 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:
- Create an access token under account settings in the Vercel dashboard, scoped to the team that will run sandboxes.
- Copy your team ID from your team settings.
- 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.
3. Define the sandbox
Create the provider with vercelSandbox, then wire it into a sandbox definition:
Our Services
import{
githubRepo,
import{ vercelSandbox }from"@tanstack/ai-sandbox-vercel"
}from"@tanstack/ai-sandbox"
defineSandbox,
const sandbox =defineSandbox({
defineWorkspace,
Brand & Design
source:githubRepo({ repo:"owner/app"}),
id:"vercel-agent",
provider:vercelSandbox({ runtime:"node24"}),
workspace:defineWorkspace({
policy:defineSandboxPolicy({
}),
}),
})
default:"allow",
setup:["pnpm install"],
defineSandboxPolicy,
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.
4. Run an agent in the sandbox
Resume and previews
import{ chat }from"@tanstack/ai"
const stream =chat({
middleware:[withSandbox(sandbox)],
adapter:grokBuildText("grok-build"),
The agent's commands now execute inside the Vercel Sandbox microVM instead of on your machine, against the cloned workspace.
import{ grokBuildText }from"@tanstack/ai-grok-build"
Pass the sandbox definition to chat through the withSandbox middleware:
})
Limitations
import{ withSandbox }from"@tanstack/ai-sandbox"
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.
messages:[{ role:"user", content:"List the project files."}],
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.
- 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.
Next 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