Skip to main content

Vercel sandboxes

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

note

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

npm install @mastra/vercel

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

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.

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

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

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
Sandbox instance identifier.

name:

'VercelSandbox'
Human-readable name.

provider:

'vercel-sandbox'
Provider type identifier.

status:

ProviderStatus
'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

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

note

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

warning

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.

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