Skip to main content

VercelMicroVMSandbox

Executes commands inside Vercel Sandbox — an ephemeral Firecracker MicroVM running Amazon Linux 2023. Provides a persistent in-session filesystem, sudo access, exposed ports, and background processes.

info

For interface details, see the WorkspaceSandbox interface.

note

This is distinct from VercelSandbox, which runs commands as stateless Vercel serverless Functions. VercelMicroVMSandbox 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 available.

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 VercelMicroVMSandbox to a workspace and assign it to an agent:

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

const workspace = new Workspace({
  sandbox: new VercelMicroVMSandbox({
    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 VercelMicroVMSandbox({
  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 4). 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.

Properties
Direct link to Properties

id:

string
Sandbox instance identifier.

name:

string
Provider name ('VercelMicroVMSandbox').

provider:

string
Provider identifier ('vercel-microvm').

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:

VercelMicroVMProcessManager
Background process manager. See [SandboxProcessManager reference](/reference/workspace/process-manager).

Background processes
Direct link to Background processes

VercelMicroVMSandbox 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 VercelMicroVMSandbox({ 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 does not 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 8 vCPUs, with 2048 MB of memory per vCPU.
  • Up to 4 exposed ports.
  • The filesystem is ephemeral — persisted only within the session and lost when the sandbox stops.
  • Maximum runtime is plan-dependent (45 minutes on Hobby, up to 5 hours on Pro/Enterprise), with a default of 5 minutes.

See the Vercel Sandbox documentation for current limits and pricing.

On this page