Vercel

The Vercel Sandbox provider uses the @vercel/sandbox SDK to run agent tasks in Vercel's ephemeral Linux microVMs. These sandboxes provide secure, isolated execution with automatic cleanup.

When to Use

Choose Vercel Sandboxes when:

You're hosting Sesame on Vercel
You want cloud-based isolation without managing containers
You need fast, on-demand compute with automatic cleanup
You're already using Vercel's ecosystem

Quick Start

# Set the provider
export SANDBOX_PROVIDER=vercel

# Authentication (choose one method below)

Authentication

The Vercel Sandbox SDK supports three authentication methods:

On Vercel (Automatic)

When running on Vercel, the SDK automatically uses OIDC tokens. No configuration needed.

Local Development

Link your project to Vercel, then pull environment variables:

vercel link
vercel env pull

This creates a .env.local file with the necessary credentials.

Self-Hosted

For self-hosted deployments, provide credentials explicitly:

export VERCEL_TEAM_ID=team_xxxxx
export VERCEL_PROJECT_ID=prj_xxxxx
export VERCEL_TOKEN=your-vercel-api-token

Get your Team ID and Project ID from your Vercel dashboard. Create an API token at vercel.com/account/tokens.

Configuration

Environment Variables

Variable	Description	Default
`SANDBOX_PROVIDER`	Set to `vercel` to enable	`local`
`VERCEL_TEAM_ID`	Your Vercel team ID	-
`VERCEL_PROJECT_ID`	Your Vercel project ID	-
`VERCEL_TOKEN`	API token (self-hosted only)	-
`VERCEL_SANDBOX_RUNTIME`	Runtime environment	`node24`
`VERCEL_SANDBOX_PORTS`	Comma-separated ports to expose	`3000,4000,5000,5173,8000,8080`
`VERCEL_SANDBOX_TIMEOUT`	Timeout in milliseconds	`3600000` (1 hour)
`VERCEL_SANDBOX_VCPUS`	Number of vCPUs (1-8)	`2`

Config File

Alternatively, configure via config.json:

{
  "sandboxProvider": {
    "type": "vercel",
    "vercel": {
      "teamId": "team_xxxxx",
      "projectId": "prj_xxxxx",
      "token": "your-token",
      "runtime": "node24",
      "ports": [3000, 5173, 8080],
      "timeout": 3600000,
      "vcpus": 2
    }
  }
}

Port Configuration

Vercel Sandboxes require ports to be declared at creation time. You cannot dynamically expose new ports after the sandbox starts.

By default, these common development ports are exposed:

3000 - Next.js, Create React App
4000 - Custom apps
5000 - Flask, custom apps
5173 - Vite
8000 - Django, FastAPI
8080 - General purpose

To customize, set VERCEL_SANDBOX_PORTS:

export VERCEL_SANDBOX_PORTS=3000,5173,8080,9000

Runtime Options

The Vercel Sandbox supports multiple runtimes:

Runtime	Description
`node24`	Node.js 24 (default)
`node22`	Node.js 22 LTS
`python3.13`	Python 3.13

export VERCEL_SANDBOX_RUNTIME=python3.13

The runtime provides the base environment. Agent CLIs (Claude Code, Codex, etc.) are installed on top of this base.

Resource Limits

Configure compute resources:

# vCPUs (1-8, default: 2)
export VERCEL_SANDBOX_VCPUS=4

# Timeout in milliseconds (default: 1 hour)
export VERCEL_SANDBOX_TIMEOUT=7200000  # 2 hours

How It Works

Sandbox Creation: When a task starts, Sesame creates a new Vercel Sandbox with the configured runtime, ports, and resources.
Project Directory: The project is cloned to /vercel/sandbox/project. This is where the agent operates.
Command Execution: Agent commands run inside the sandbox. Output is streamed back to Sesame in real-time.
Port Access: Exposed ports get public URLs via sandbox.domain(port). These are automatically available for preview.
Cleanup: When the task completes (or times out), the sandbox is automatically destroyed.

Limitations

Aspect	Limitation
Ports	Must be declared at creation time
Working directory	Always `/vercel/sandbox/project`
OS-level sandboxing	Not used (Vercel's cloud VMs provide full isolation)
Persistence	Sandboxes are ephemeral - no data persists

The @anthropic-ai/sandbox-runtime OS-level sandboxing feature (used by Filesystem and Docker providers) is not applicable to Vercel sandboxes. This is because Vercel's cloud microVMs already provide complete process and network isolation at the infrastructure level.

Comparison with Other Providers

Feature	Vercel	Docker	Filesystem
Isolation	Cloud VM	Container	Process
Setup	API credentials	Docker installed	None
Persistence	None	Optional volumes	Full
Port exposure	Declared upfront	Dynamic	Dynamic
Cleanup	Automatic	Manual/auto	Manual
Best for	Vercel hosting	Self-hosted production	Development

Troubleshooting

"Port X was not declared at sandbox creation"

Add the port to VERCEL_SANDBOX_PORTS before starting the task:

export VERCEL_SANDBOX_PORTS=3000,5173,8080,YOUR_PORT

Authentication Errors

On Vercel: Ensure your project is properly linked and deployed
Local: Run vercel link && vercel env pull
Self-hosted: Verify VERCEL_TEAM_ID, VERCEL_PROJECT_ID, and VERCEL_TOKEN are set correctly

Sandbox Timeout

Increase the timeout for long-running tasks:

export VERCEL_SANDBOX_TIMEOUT=7200000  # 2 hours

Resource Limits

If tasks are running slowly, increase vCPUs:

export VERCEL_SANDBOX_VCPUS=4

On this page