> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# VercelSandbox

[Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) 内でコマンドを実行します。これは Amazon Linux 2023 を実行する一時的な [Firecracker](https://firecracker-microvm.github.io/) MicroVM です。セッション内で永続化される Filesystem、`sudo` アクセス、公開ポート、バックグラウンドプロセスを提供します。インターフェースの詳細は、[WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)を参照してください。

> **注記:** これは、ステートレスな Vercel サーバーレス **Function** としてコマンドを実行する [`VercelServerlessSandbox`](https://mastra.zisheng.pro/ja/reference/workspace/vercel-serverless) とは異なります。`VercelSandbox` は、永続的な Filesystem と長時間稼働するプロセスを備えた完全な Linux MicroVM を実行します。

## インストール

**npm**:

```bash
npm install @mastra/vercel
```

**pnpm**:

```bash
pnpm add @mastra/vercel
```

**Yarn**:

```bash
yarn add @mastra/vercel
```

**Bun**:

```bash
bun add @mastra/vercel
```

## 認証

明示的な認証情報を指定しない場合、`@vercel/sandbox` SDK は Vercel OIDC トークンを自動的に使用します。`token`、`teamId`、`projectId` のいずれかを指定する場合は、3つすべてを指定してください。

**OIDC（推奨）**:

ローカル開発では、プロジェクトをリンクして開発用トークンを取得します。

```bash
vercel link
vercel env pull
```

Vercel 上では認証が自動的に処理されるため、設定は不要です。

**アクセストークン（.env）**:

OIDC を利用できない環境では、3つの値をすべて指定します。

```bash
VERCEL_TOKEN=your-token
VERCEL_TEAM_ID=your-team-id
VERCEL_PROJECT_ID=your-project-id
```

**コンストラクター**:

```typescript
new VercelSandbox({
  token: 'your-token',
  teamId: 'your-team-id',
  projectId: 'your-project-id',
})
```

## 使用方法

Workspace に `VercelSandbox` を追加して Agent に割り当てます。

```typescript
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 内で動作するネットワークサービスへアクセスするためのポートを公開します。

```typescript
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` コールバックを介して、コマンド出力をリアルタイムでストリーミングします。

```typescript
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 インスタンスの一意な識別子。 (Default: `Auto-generated`)

**sandboxName** (`string`): Vercel API に渡す任意の名前。省略すると自動生成されます。

**token** (`string`): Vercel API トークン。未指定の場合は環境変数 VERCEL\_TOKEN を使用します。OIDC トークンを使用する場合は省略します。

**teamId** (`string`): Vercel チーム ID。未指定の場合は環境変数 VERCEL\_TEAM\_ID を使用します。

**projectId** (`string`): Vercel プロジェクト ID。未指定の場合は環境変数 VERCEL\_PROJECT\_ID を使用します。

**runtime** (`'node24' | 'node22' | 'node26' | 'python3.13'`): Sandbox のランタイム。 (Default: `'node24'`)

**timeout** (`number`): Sandbox が自動終了するまでのタイムアウト（ミリ秒）。 (Default: `300000 (5 minutes)`)

**resources** (`{ vcpus?: number }`): リソース割り当て。各 vCPU に 2048 MB のメモリが付属します。

**ports** (`number[]`): Sandbox から公開するポート（最大15個）。公開 HTTPS ドメインは getInfo().metadata.domains で取得できます。

**env** (`Record<string, string>`): すべてのコマンドが継承するデフォルト環境変数。 (Default: `{}`)

**metadata** (`Record<string, unknown>`): getInfo() で公開するカスタムメタデータ。 (Default: `{}`)

**instructions** (`string | ((opts) => string)`): getInstructions() が返すデフォルトの指示を上書きします。置き換えるには文字列を、デフォルトを拡張するには関数を渡します。

**onStart** (`SandboxLifecycleHook`): Sandbox が running ステータスになった後に呼び出すライフサイクルフック。

**onStop** (`SandboxLifecycleHook`): Sandbox の停止前に呼び出すライフサイクルフック。

**onDestroy** (`SandboxLifecycleHook`): Sandbox の破棄前に呼び出すライフサイクルフック。

## プロパティ

**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 内でデタッチ済みコマンドとして動作し、出力はコマンドログを介してストリーミングされます。

```typescript
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` リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/process-manager)を参照してください。

> **注記:** 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 ドキュメント](https://vercel.com/docs/vercel-sandbox)を参照してください。