@mastra/vercel

@mastra/vercel

Vercel workspace sandbox providers for Mastra.

This package exposes two Vercel-backed sandbox implementations:

• VercelSandbox runs commands in a Vercel Sandbox (MicroVM).
• VercelServerlessSandbox runs commands as stateless Vercel Functions.

Use VercelSandbox when you need a Linux environment with a filesystem, exposed ports, or background processes. Use VercelServerlessSandbox when you need short-lived, stateless command execution backed by Vercel Functions.

Installation

npm install @mastra/vercel

VercelSandbox

VercelSandbox executes commands inside Vercel Sandbox, an ephemeral Firecracker MicroVM running Amazon Linux 2023.

Use it when your agent or workflow needs:

• a Linux filesystem for the sandbox session
• sudo access
• exposed ports for preview servers
• background processes
• command execution with streamed output

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

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

const result = await workspace.sandbox.executeCommand('node', ['--version']);
console.log(result.stdout);

Authentication

When Vercel OIDC is available, VercelSandbox can authenticate automatically. Outside an OIDC environment, provide Vercel credentials directly or through environment variables:

export VERCEL_TOKEN="..."
export VERCEL_TEAM_ID="team_..."
export VERCEL_PROJECT_ID="prj_..."

const sandbox = new VercelSandbox({
  token: process.env.VERCEL_TOKEN,
  teamId: process.env.VERCEL_TEAM_ID,
  projectId: process.env.VERCEL_PROJECT_ID,
});

Resources and exposed ports

Use resources.vcpus to request CPU capacity and ports to expose services from the sandbox.

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

await sandbox.start();
await sandbox.executeCommand('npm', ['run', 'dev'], { background: true });

const info = await sandbox.getInfo();
console.log(info.metadata.domains);

Vercel supports up to 8 vCPUs and up to 4 exposed ports per sandbox. Memory is allocated at 2048 MB per vCPU.

Streaming command output

const result = await sandbox.executeCommand('npm', ['test'], {
  onStdout: chunk => process.stdout.write(chunk),
  onStderr: chunk => process.stderr.write(chunk),
});

console.log(result.exitCode);

Background processes

VercelSandbox includes VercelSandboxProcessManager, so you can start and manage background processes.

const process = await sandbox.processes.spawn('npm run dev');

console.log(process.pid);

await process.kill();

Options

Option	Type	Default	Description
id	string	generated	Unique identifier for this sandbox instance.
sandboxName	string	generated by Vercel	Optional sandbox name passed to the Vercel API.
token	string	VERCEL_TOKEN	Vercel API token. Omit when OIDC authentication is available.
teamId	string	VERCEL_TEAM_ID	Vercel team ID.
projectId	string	VERCEL_PROJECT_ID	Vercel project ID.
runtime	'node24' | 'node22' | 'node26' | 'python3.13'	'node24'	Sandbox runtime.
timeout	number	300_000	Timeout in milliseconds before the sandbox auto-terminates.
resources	{ vcpus?: number }	undefined	Resources to allocate.
ports	number[]	undefined	Ports to expose from the sandbox.
env	Record<string, string>	{}	Default environment variables inherited by all commands.
metadata	Record<string, unknown>	{}	Custom metadata surfaced by getInfo().
instructions	string | (opts) => string	default instructions	Custom instructions returned by getInstructions().

VercelServerlessSandbox

VercelServerlessSandbox executes commands as Vercel serverless Functions. It deploys an executor function and invokes it over HTTP.

Use it when you want short-lived command execution without managing infrastructure.

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

const workspace = new Workspace({
  sandbox: new VercelServerlessSandbox({
    token: process.env.VERCEL_TOKEN,
    teamId: process.env.VERCEL_TEAM_ID,
    regions: ['iad1'],
    maxDuration: 60,
    memory: 1024,
  }),
});

const result = await workspace.sandbox.executeCommand('node', ['--version']);
console.log(result.stdout);

Authentication

VercelServerlessSandbox requires a Vercel API token. Pass token or set VERCEL_TOKEN.

export VERCEL_TOKEN="..."

const sandbox = new VercelServerlessSandbox({
  token: process.env.VERCEL_TOKEN,
  teamId: process.env.VERCEL_TEAM_ID,
});

Options

Option	Type	Default	Description
token	string	VERCEL_TOKEN	Vercel API token.
teamId	string	undefined	Vercel team ID for team-scoped deployments.
projectName	string	generated	Existing Vercel project name. Auto-generated if omitted.
regions	string[]	['iad1']	Deployment regions.
maxDuration	number	60	Function max duration in seconds.
memory	number	1024	Function memory in MB.
env	Record<string, string>	{}	Environment variables baked into the deployed function.
commandTimeout	number	55_000	Per-invocation command timeout in milliseconds.
instructions	string | (opts) => string	default instructions	Custom instructions returned by getInstructions().

Limitations

VercelServerlessSandbox is stateless. It doesn't provide:

• a persistent filesystem
• an interactive shell
• long-running background processes
• mounted directories

Only /tmp is writable during a function invocation.

Editor provider descriptors

Use the provider descriptors when registering Vercel sandboxes with the Mastra editor.

import { MastraEditor } from '@mastra/core/editor';
import { vercelSandboxProvider, vercelServerlessSandboxProvider } from '@mastra/vercel';

const editor = new MastraEditor({
  sandboxes: [vercelSandboxProvider, vercelServerlessSandboxProvider],
});

Provider	ID	Creates
vercelSandboxProvider	vercel-sandbox	VercelSandbox
vercelServerlessSandboxProvider	vercel-serverless	VercelServerlessSandbox