---
title: Using TanStack AI with Vercel Sandbox
description: 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.
url: /kb/guide/tanstack-ai-vercel-sandbox
canonical_url: "https://vercel.com/kb/guide/tanstack-ai-vercel-sandbox"
published: 2026-09-08
last_updated: 2026-09-08
authors: Ben Sabic
related:
  - /docs/cli
  - /docs/sandbox
  - /docs/accounts
  - /docs/project-configuration/general-settings
  - /kb/guide/tanstack-ai-vercel-ai-gateway
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

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.

## Overview

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
  

## Prerequisites

Before you begin, make sure you have:

- A [Vercel account](https://vercel.com/signup)
  
- A TanStack AI project with `@tanstack/ai` installed
  
- A [harness adapter](https://tanstack.com/ai/latest/docs/sandbox/harnesses) 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](https://vercel.com/docs/cli).

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

The Vercel provider runs each sandbox as a managed [Vercel Sandbox](https://vercel.com/docs/sandbox) microVM. It supports persistent resume-by-id with a durable filesystem, and exposed-port domains for previewing whatever the agent builds.

## Steps

### 1\. Install the packages

Install the sandbox core and the Vercel provider:

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

### 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:

```bash
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](https://vercel.com/account/settings/tokens) in the Vercel dashboard, scoped to the team that will run sandboxes.
   
2. Copy your team ID from your [team settings](https://vercel.com/docs/accounts#find-your-team-id).
   
3. Copy your project ID from the project's [general settings](https://vercel.com/docs/project-configuration/general-settings#project-id).
   

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:

```typescript
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](https://tanstack.com/ai/latest/docs/adapters/grok-build) and [Codex](https://tanstack.com/ai/latest/docs/adapters/codex) on auto-approve, with the microVM boundary providing the isolation. Use [Claude Code](https://tanstack.com/ai/latest/docs/adapters/claude-code) as the harness when you need command-level deny rules.
  

### 4\. Run an agent in the sandbox

Pass the sandbox definition to `chat` through the `withSandbox` middleware:

```typescript
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.

## Resume 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.

## Limitations

- **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](https://vercel.com/docs/sandbox)
  
- Explore workspaces, policies, and harnesses in the [TanStack AI sandbox docs](https://tanstack.com/ai/latest/docs/sandbox/overview)
  
- Route the same app's model calls through one API key with [Vercel AI Gateway](https://vercel.com/kb/guide/tanstack-ai-vercel-ai-gateway)