Skip to main content

VercelServerlessSandbox

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

info

For interface details, see WorkspaceSandbox interface.

warning

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

note

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
Direct link to Installation

npm install @mastra/vercel

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

onStart?:

SandboxLifecycleHook
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
Direct link to 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
Direct link to 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).
On this page