VercelSandbox
Vercel Sandbox 内でコマンドを実行します。これは Amazon Linux 2023 を実行する一時的な Firecracker MicroVM です。セッション内で永続化される Filesystem、sudo アクセス、公開ポート、バックグラウンドプロセスを提供します。インターフェースの詳細は、WorkspaceSandbox インターフェースを参照してください。
これは、ステートレスな Vercel サーバーレス Function としてコマンドを実行する VercelServerlessSandbox とは異なります。VercelSandbox は、永続的な Filesystem と長時間稼働するプロセスを備えた完全な 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、teamId、projectId のいずれかを指定する場合は、3つすべてを指定してください。
- OIDC（推奨）
- アクセストークン（.env）
- コンストラクター
ローカル開発では、プロジェクトをリンクして開発用トークンを取得します。
vercel link
vercel env pull
Vercel 上では認証が自動的に処理されるため、設定は不要です。
OIDC を利用できない環境では、3つの値をすべて指定します。
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',
})
使用方法使用方法への直接リンク
Workspace に VercelSandbox を追加して 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（1 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 ステータスになった後に呼び出すライフサイクルフック。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 チャネルを公開しないため、handle.sendStdin() はエラーをスローします。この Provider は Filesystem のマウント（FUSE）にも対応していません。
制限制限への直接リンク
- 最大32 vCPU。1 vCPU あたり 2048 MB のメモリ。
- 公開ポートは最大15個。
- Filesystem は一時的です。セッション内でのみ維持され、Sandbox の停止時に失われます。
- 最大実行時間はプランによって異なり（Hobby は45分、Pro と Enterprise は最大24時間）、デフォルトは5分です。
現在の制限と料金は、Vercel Sandbox ドキュメントを参照してください。