VercelSandbox
在 Vercel Sandbox 內執行指令。Vercel Sandbox 是執行 Amazon Linux 2023 的臨時 Firecracker MicroVM，提供在工作階段內持續保留的檔案系統、sudo 存取權、公開連接埠及背景程序。介面詳情請參閱 WorkspaceSandbox 介面。
這有別於 VercelServerlessSandbox，後者會以無狀態 Vercel serverless Functions 執行指令。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（建議）
- 存取 token（.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 callback 即時串流傳送指令輸出：
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),
})
兩個 callback 均屬選填，可獨立使用。
建構函式參數建構函式參數 的直接連結
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 包含一個程序管理器，用於產生及管理背景程序。每個產生的程序都會在 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 停止時遺失。
- 執行時間上限視乎方案而定（Hobby 為 45 分鐘，Pro 及 Enterprise 最長可達 24 小時），預設為 5 分鐘。
有關目前的限制及定價，請參閱 Vercel Sandbox 文件。