跳至主要內容

VercelSandbox

在 Vercel Sandbox 內執行指令；這是執行 Amazon Linux 2023 的暫時性 Firecracker MicroVM。它提供工作階段內持久的檔案系統、sudo 存取權、公開連接埠與背景處理程序。介面詳情請參閱 WorkspaceSandbox 介面。

備註

這與 VercelServerlessSandbox 不同；後者會將指令執行為無狀態的 Vercel Serverless Functions。VercelSandbox 執行完整的 Linux MicroVM，具備持久檔案系統與長時間執行的處理程序。

安裝
「安裝」的直接連結

npm install @mastra/vercel

驗證
「驗證」的直接連結

未提供明確認證時，@vercel/sandbox SDK 會自動使用 Vercel OIDC Token。如果提供 token、teamId 或 projectId，請同時提供這三個值。

進行本機開發時，請連結專案並取得開發 Token：

vercel link
vercel env pull

在 Vercel 上，驗證會自動處理，不需要任何設定。

使用方式
「使用方式」的直接連結

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

string
= 自動產生
此 Sandbox 執行個體的唯一識別碼。

sandboxName?:

string
傳給 Vercel API 的選用名稱。省略時會自動產生。

token?:

string
Vercel API Token。若未提供，會改用 VERCEL_TOKEN 環境變數；省略即可使用 OIDC Token。

teamId?:

string
Vercel 團隊 ID。若未提供，會改用 VERCEL_TEAM_ID 環境變數。

projectId?:

string
Vercel 專案 ID。若未提供，會改用 VERCEL_PROJECT_ID 環境變數。

runtime?:

'node24' | 'node22' | 'node26' | 'python3.13'
= 'node24'
Sandbox 執行階段。

timeout?:

number
= 300000（5 分鐘）
Sandbox 自動終止前的逾時時間，單位為毫秒。

resources?:

{ vcpus?: number }
資源設定。每個 vCPU 配有 2048 MB 記憶體。

ports?:

number[]
要從 Sandbox 公開的連接埠（最多 15 個）。可透過 getInfo().metadata.domains 取得公開 HTTPS 網域。

env?:

Record<string, string>
= {}
所有指令都會繼承的預設環境變數。

metadata?:

Record<string, unknown>
= {}
透過 getInfo() 公開的自訂中繼資料。

instructions?:

string | ((opts) => string)
覆寫 getInstructions() 傳回的預設指示。傳入字串可取代預設指示，或傳入函式加以擴充。

onStart?:

SandboxLifecycleHook
Sandbox 達到 running 狀態後呼叫的生命週期 hook。

onStop?:

SandboxLifecycleHook
Sandbox 停止前呼叫的生命週期 hook。

onDestroy?:

SandboxLifecycleHook
Sandbox 銷毀前呼叫的生命週期 hook。

屬性
「屬性」的直接連結

id:

string
Sandbox 執行個體識別碼。

name:

'VercelSandbox'
易讀名稱。

provider:

'vercel-sandbox'
Provider 類型識別碼。

status:

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

sandbox:

Sandbox
底層 @vercel/sandbox Sandbox 執行個體。如果 Sandbox 尚未啟動，會擲回 SandboxNotReadyError。

processes:

VercelSandboxProcessManager
背景處理程序管理器。請參閱 SandboxProcessManager 參考。

背景處理程序
「背景處理程序」的直接連結

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 通道，因此 handle.sendStdin() 會擲回錯誤。此 Provider 也不支援檔案系統掛載（FUSE）。

限制
「限制」的直接連結

  • 最多 32 個 vCPU，每個 vCPU 配有 2048 MB 記憶體。
  • 最多公開 15 個連接埠。
  • 檔案系統是暫時性的，只會在工作階段內持久保存，並在 Sandbox 停止時遺失。
  • 最長執行時間依方案而異（Hobby 為 45 分鐘，Pro 與 Enterprise 最長 24 小時），預設為 5 分鐘。

目前的限制與價格請參閱 Vercel Sandbox 文件。

On this page