Vercel Sandboxes

Run commands in isolated Vercel environments with either persistent Sandbox microVMs or stateless Serverless Functions.

Vercel Sandbox
Vercel Sandbox的直接链接

Executes commands inside Vercel Sandbox which is an ephemeral Firecracker MicroVM running Amazon Linux 2023. Provides a persistent in-session filesystem, sudo access, exposed ports, and background processes. For interface details, see the WorkspaceSandbox interface.

备注

This is distinct from VercelServerlessSandbox, which runs commands as stateless Vercel serverless Functions. VercelSandbox runs a full Linux MicroVM with a persistent filesystem and long-running processes.

Installation
Installation的直接链接

npm
pnpm
Yarn
Bun

npm install @mastra/vercel

pnpm add @mastra/vercel

yarn add @mastra/vercel

bun add @mastra/vercel

Authentication
Authentication的直接链接

The @vercel/sandbox SDK uses a Vercel OIDC token automatically when no explicit credentials are provided. If you provide token, teamId, or projectId, provide all three values together.

OIDC (recommended)
Access token (.env)
Constructor

For local development, link the project and pull a development token:

vercel link
vercel env pull

On Vercel, authentication is handled automatically — no configuration needed.

For environments without OIDC, provide all three values together:

VERCEL_TOKEN=your-token
VERCEL_TEAM_ID=your-team-id
VERCEL_PROJECT_ID=your-project-id

new VercelSandbox({
  token: 'your-token',
  teamId: 'your-team-id',
  projectId: 'your-project-id',
})

Usage
Usage的直接链接

Add a VercelSandbox to a workspace and assign it to an agent:

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { VercelSandbox } from '@mastra/vercel'

const workspace = new Workspace({
  sandbox: new VercelSandbox({
    runtime: 'node24',
    timeout: 600_000,
  }),
})

const agent = new Agent({
  id: 'code-agent',
  name: 'Code Agent',
  instructions: 'You are a coding assistant working in this workspace.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

const response = await agent.generate('Print "Hello, world!" and show the Node.js version.')

console.log(response.text)

Resources and exposed ports
Resources and exposed ports的直接链接

Allocate vCPUs (2048 MB of memory per vCPU) and expose ports to reach network services running inside the sandbox:

const sandbox = new VercelSandbox({
  runtime: 'node24',
  resources: { vcpus: 4 },
  ports: [3000],
})

const workspace = new Workspace({ sandbox })
await sandbox.start()

// The public HTTPS domain for an exposed port is available via getInfo()
const { metadata } = sandbox.getInfo()
console.log(metadata?.domains) // { 3000: 'https://....vercel.run' }

Streaming output
Streaming output的直接链接

Stream command output in real time via onStdout and onStderr callbacks:

await sandbox.executeCommand('sh', ['-c', 'for i in 1 2 3; do echo "line $i"; sleep 1; done'], {
  onStdout: chunk => process.stdout.write(chunk),
  onStderr: chunk => process.stderr.write(chunk),
})

Both callbacks are optional and can be used independently.

Constructor parameters
Constructor parameters的直接链接

id?:

string

= Auto-generated

Unique identifier for this sandbox instance.

sandboxName?:

string

Optional name passed to the Vercel API. Auto-generated if omitted.

token?:

string

Vercel API token. Falls back to the VERCEL_TOKEN environment variable. Omit to use the OIDC token.

teamId?:

string

Vercel team ID. Falls back to the VERCEL_TEAM_ID environment variable.

projectId?:

string

Vercel project ID. Falls back to the VERCEL_PROJECT_ID environment variable.

runtime?:

'node24' | 'node22' | 'node26' | 'python3.13'

= 'node24'

Sandbox runtime.

timeout?:

number

= 300000 (5 minutes)

Timeout in milliseconds before the sandbox auto-terminates.

resources?:

{ vcpus?: number }

Resource allocation. Each vCPU comes with 2048 MB of memory.

ports?:

number[]

Ports to expose from the sandbox (up to 15). Public HTTPS domains are available via getInfo().metadata.domains.

env?:

Record<string, string>

= {}

Default environment variables inherited by all commands.

workingDirectory?:

string

Default directory for command execution when no per-command cwd is given. A per-command cwd always wins. Use an absolute path.

metadata?:

Record<string, unknown>

= {}

Custom metadata surfaced via getInfo().

instructions?:

string | ((opts) => string)

Override the default instructions returned by getInstructions(). Pass a string to replace them, or a function to extend the defaults.

onStart?:

SandboxStartHook

Lifecycle hook called after the sandbox reaches running status.

onStop?:

SandboxLifecycleHook

Lifecycle hook called before the sandbox stops.

onDestroy?:

SandboxLifecycleHook

Lifecycle hook called before the sandbox is destroyed.

Properties
Properties的直接链接

id:

string

Sandbox instance identifier.

name:

'VercelSandbox'

Human-readable name.

provider:

'vercel-sandbox'

Provider type identifier.

status:

ProviderStatus

sandbox:

Sandbox

The underlying @vercel/sandbox Sandbox instance. Throws SandboxNotReadyError if the sandbox has not been started.

processes:

VercelSandboxProcessManager

Background process manager. See SandboxProcessManager reference.

Background processes
Background processes的直接链接

VercelSandbox includes a process manager for spawning and managing background processes. Each spawned process runs as a detached command inside the MicroVM, with output streamed through the command logs.

const sandbox = new VercelSandbox({ runtime: 'node24', ports: [3000] })
await sandbox.start()

const handle = await sandbox.processes.spawn('node server.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

console.log(handle.stdout)
await handle.kill()

See the SandboxProcessManager reference for the full API.

备注

The Vercel Sandbox SDK doesn't expose a stdin channel for running commands, so handle.sendStdin() throws. Filesystem mounting (FUSE) is also not supported by this provider.

Limits
Limits的直接链接

Up to 32 vCPUs, with 2048 MB of memory per vCPU.
Up to 15 exposed ports.
The filesystem is ephemeral. It's persisted only within the session and lost when the sandbox stops.
Maximum runtime is plan-dependent (45 minutes on Hobby, up to 24 hours on Pro and Enterprise), with a default of 5 minutes.

See the Vercel Sandbox documentation for current limits and pricing.

Vercel Serverless Sandbox
Vercel Serverless Sandbox的直接链接

VercelServerlessSandbox executes commands as Vercel serverless functions. It provides globally distributed, zero-infrastructure execution with automatic scaling. For interface details, see the WorkspaceSandbox interface.

注意

VercelServerlessSandbox is stateless. It doesn't provide a persistent filesystem, interactive shell, or long-running background processes. Only /tmp is writable, and it's ephemeral between invocations.

备注

For a full Linux MicroVM with a persistent filesystem, sudo access, exposed ports, and background processes, use VercelSandbox, which is backed by the Vercel Sandbox product.

Installation
Installation的直接链接

npm
pnpm
Yarn
Bun

npm install @mastra/vercel

pnpm add @mastra/vercel

yarn add @mastra/vercel

bun add @mastra/vercel

Usage
Usage的直接链接

Add a VercelServerlessSandbox to a workspace and assign it to an agent:

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { VercelServerlessSandbox } from '@mastra/vercel'

const workspace = new Workspace({
  sandbox: new VercelServerlessSandbox({
    token: process.env.VERCEL_TOKEN,
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  name: 'dev-agent',
  instructions: 'You are a coding assistant working in this workspace.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

Team-scoped deployment with custom resources
Team-scoped deployment with custom resources的直接链接

const workspace = new Workspace({
  sandbox: new VercelServerlessSandbox({
    token: process.env.VERCEL_TOKEN,
    teamId: 'team_abc123',
    regions: ['iad1', 'sfo1'],
    maxDuration: 120,
    memory: 3008,
    env: {
      NODE_ENV: 'production',
    },
  }),
})

Constructor parameters
Constructor parameters的直接链接

token?:

string

Vercel API token. Falls back to VERCEL_TOKEN environment variable.

teamId?:

string

Vercel team ID for team-scoped deployments.

projectName?:

string

Existing Vercel project name. Auto-generated if omitted.

regions?:

string[]

= ['iad1']

Deployment regions.

maxDuration?:

number

= 60

Function maximum duration in seconds.

memory?:

number

= 1024

Function memory in MB.

env?:

Record<string, string>

Environment variables baked into the deployed function source. These are embedded at deploy time, not set dynamically.

workingDirectory?:

string

Default directory for command execution when no per-command cwd is given. A per-command cwd always wins. When omitted, commands fall back to /tmp and sandbox.workingDirectory stays undefined.

commandTimeout?:

number

= 55000

Per-invocation command timeout in milliseconds.

instructions?:

string | ((opts) => string)

Custom instructions that override the default instructions returned by getInstructions(). Pass a string to fully replace, or a function to extend the defaults.

onStart?:

SandboxStartHook

Lifecycle hook called after the sandbox reaches running status.

onStop?:

SandboxLifecycleHook

Lifecycle hook called before the sandbox stops.

onDestroy?:

SandboxLifecycleHook

Lifecycle hook called before the sandbox is destroyed.

Properties
Properties的直接链接

id:

string

Unique identifier for this sandbox instance.

name:

'VercelServerlessSandbox'

Human-readable name.

provider:

'vercel-serverless'

Provider type identifier.

status:

ProviderStatus

Current lifecycle status: 'pending', 'starting', 'running', 'stopping', 'stopped', 'destroying', 'destroyed', or 'error'.

Limitations
Limitations的直接链接

VercelServerlessSandbox uses serverless functions under the hood, which means:

No persistent filesystem: Files written to /tmp are ephemeral and cleared between invocations.
No interactive shell: Commands run via /bin/sh -c with no stdin streaming.
No background processes: No process manager, PIDs, or long-running tasks.
No mounting: Cloud storage mounting (S3, GCS) isn't supported.
Timeout limits: Maximum execution time is bounded by maxDuration (default 60s).

WorkspaceSandbox interface
Workspace class
E2B sandbox: Full-featured cloud sandbox with persistent filesystem and process management

Vercel SandboxVercel Sandbox的直接链接

InstallationInstallation的直接链接

AuthenticationAuthentication的直接链接

UsageUsage的直接链接

Resources and exposed portsResources and exposed ports的直接链接

Streaming outputStreaming output的直接链接

Constructor parametersConstructor parameters的直接链接

id?:

sandboxName?:

token?:

teamId?:

projectId?:

runtime?:

timeout?:

resources?:

ports?:

env?:

workingDirectory?:

metadata?:

instructions?:

onStart?:

onStop?:

onDestroy?:

PropertiesProperties的直接链接

id:

name:

provider:

status:

sandbox:

processes:

Background processesBackground processes的直接链接

LimitsLimits的直接链接

Vercel Serverless SandboxVercel Serverless Sandbox的直接链接

InstallationInstallation的直接链接

UsageUsage的直接链接

Team-scoped deployment with custom resourcesTeam-scoped deployment with custom resources的直接链接

Constructor parametersConstructor parameters的直接链接

token?:

teamId?:

projectName?:

regions?:

maxDuration?:

memory?:

env?:

workingDirectory?:

commandTimeout?:

instructions?:

onStart?:

onStop?:

onDestroy?:

PropertiesProperties的直接链接

id:

name:

provider:

status:

LimitationsLimitations的直接链接

RelatedRelated的直接链接

Vercel Sandbox
Vercel Sandbox的直接链接

Installation
Installation的直接链接

Authentication
Authentication的直接链接

Usage
Usage的直接链接

Resources and exposed ports
Resources and exposed ports的直接链接

Streaming output
Streaming output的直接链接

Constructor parameters
Constructor parameters的直接链接

Properties
Properties的直接链接

Background processes
Background processes的直接链接

Limits
Limits的直接链接

Vercel Serverless Sandbox
Vercel Serverless Sandbox的直接链接

Installation
Installation的直接链接

Usage
Usage的直接链接

Team-scoped deployment with custom resources
Team-scoped deployment with custom resources的直接链接

Constructor parameters
Constructor parameters的直接链接

Properties
Properties的直接链接

Limitations
Limitations的直接链接

Related
Related的直接链接