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

# VercelSandbox

在 [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) 內執行指令；這是執行 Amazon Linux 2023 的暫時性 [Firecracker](https://firecracker-microvm.github.io/) MicroVM。它提供工作階段內持久的檔案系統、`sudo` 存取權、公開連接埠與背景處理程序。介面詳情請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/sandbox)。

> **備註:** 這與 [`VercelServerlessSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/vercel-serverless) 不同；後者會將指令執行為無狀態的 Vercel Serverless **Functions**。`VercelSandbox` 執行完整的 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。如果提供 `token`、`teamId` 或 `projectId`，請同時提供這三個值。

**OIDC（建議）**:

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

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

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

**存取 Token（.env）**:

在沒有 OIDC 的環境中，請同時提供這三個值：

```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',
})
```

## 使用方式

將 `VercelSandbox` 加入 Workspace，並指派給 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（每個 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: `自動產生`)

**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'`): Sandbox 執行階段。 (Default: `'node24'`)

**timeout** (`number`): Sandbox 自動終止前的逾時時間，單位為毫秒。 (Default: `300000（5 分鐘）`)

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

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

**env** (`Record<string, string>`): 所有指令都會繼承的預設環境變數。 (Default: `{}`)

**metadata** (`Record<string, unknown>`): 透過 getInfo() 公開的自訂中繼資料。 (Default: `{}`)

**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 內以分離式指令執行，並透過指令記錄串流輸出。

```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/zh-TW/reference/workspace/process-manager)。

> **備註:** Vercel Sandbox SDK 不會公開執行指令所需的 stdin 通道，因此 `handle.sendStdin()` 會擲回錯誤。此 Provider 也不支援檔案系統掛載（FUSE）。

## 限制

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

目前的限制與價格請參閱 [Vercel Sandbox 文件](https://vercel.com/docs/vercel-sandbox)。