Skip to main content

VercelSandbox

Executes commands as Vercel serverless functions. Provides globally-distributed, zero-infrastructure execution with automatic scaling.

info

For interface details, see WorkspaceSandbox interface.

warning

VercelSandbox is stateless. There is no persistent filesystem, no interactive shell, and no support for long-running or background processes. Only /tmp is writable and is ephemeral between invocations.

Installation
Direct link to Installation

npm install @mastra/vercel

Usage
Direct link to 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({
    token: process.env.VERCEL_TOKEN,
  }),
})

const agent = new Agent({
  name: 'dev-agent',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

Team-scoped deployment with custom resources
Direct link to Team-scoped deployment with custom resources

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

Constructor parameters
Direct link to 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.

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.

Properties
Direct link to Properties

id:

string
Unique identifier for this sandbox instance.

name:

'VercelSandbox'
Human-readable name.

provider:

'vercel'
Provider type identifier.

status:

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

Limitations
Direct link to Limitations

VercelSandbox 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) is not supported.
  • Timeout limits: Maximum execution time is bounded by maxDuration (default 60s).
On this page