VercelSandbox
在 Vercel Sandbox 中执行命令。Vercel Sandbox 是运行 Amazon Linux 2023 的临时 Firecracker MicroVM。它提供会话期间持久化的文件系统、sudo 访问权限、端口暴露和后台进程。有关接口详情，请参阅 WorkspaceSandbox 接口。
它不同于 VercelServerlessSandbox，后者会以无状态 Vercel serverless Function 的形式运行命令。VercelSandbox 运行完整的 Linux MicroVM，具有持久文件系统并支持长时间运行的进程。
安装安装的直接链接
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/vercel
pnpm add @mastra/vercel
yarn add @mastra/vercel
bun add @mastra/vercel
身份验证身份验证的直接链接
未提供显式凭据时，@vercel/sandbox SDK 会自动使用 Vercel OIDC token。如果提供 token、teamId 或 projectId 中的任意一个，请同时提供全部三个值。
- OIDC（推荐）
- 访问令牌（.env）
- 构造函数
对于本地开发，请关联项目并拉取开发 token：
vercel link
vercel env pull
在 Vercel 上，身份验证会自动处理，无需配置。
在没有 OIDC 的环境中，请同时提供全部三个值：
VERCEL_TOKEN=your-token
VERCEL_TEAM_ID=your-team-id
VERCEL_PROJECT_ID=your-project-id
new VercelSandbox({
token: 'your-token',
teamId: 'your-team-id',
projectId: 'your-project-id',
})
用法用法的直接链接
将 VercelSandbox 添加到 Workspace，并将其分配给 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)
资源和暴露端口资源和暴露端口的直接链接
分配 vCPU（每个 vCPU 配备 2048 MB 内存）并暴露端口，以访问 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' }
流式输出流式输出的直接链接
通过 onStdout 和 onStderr 回调实时流式传输命令输出：
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),
})
两个回调均为可选，并且可以单独使用。
构造函数参数构造函数参数的直接链接
id?:
sandboxName?:
token?:
teamId?:
projectId?:
runtime?:
timeout?:
resources?:
ports?:
env?:
metadata?:
instructions?:
onStart?:
running 状态后调用的 lifecycle hook。onStop?:
onDestroy?:
属性属性的直接链接
id:
name:
provider:
status:
sandbox:
processes:
后台进程后台进程的直接链接
VercelSandbox 包含用于生成和管理后台进程的进程管理器。每个生成的进程都以 detached command 的形式在 MicroVM 中运行，其输出通过命令日志以流式方式传输。
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()
如需完整 API，请参阅 SandboxProcessManager 参考。
Vercel Sandbox SDK 不会为正在运行的命令公开 stdin channel，因此 handle.sendStdin() 会抛出错误。此 Provider 也不支持文件系统挂载（FUSE）。
限制限制的直接链接
- 最多 32 个 vCPU，每个 vCPU 配备 2048 MB 内存。
- 最多暴露 15 个端口。
- 文件系统是临时的。它只在会话期间持久保留，并会在 Sandbox 停止时丢失。
- 最大 runtime 取决于套餐（Hobby 为 45 分钟，Pro 和 Enterprise 最长 24 小时），默认为 5 分钟。
有关当前限制和价格，请参阅 Vercel Sandbox 文档。