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

# VercelSandbox

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

> **備註:** 這有別於 [`VercelServerlessSandbox`](https://mastra.zisheng.pro/zh-HK/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` callback 即時串流傳送指令輸出：

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

兩個 callback 均屬選填，可獨立使用。

## 建構函式參數

**id** (`string`): 此 sandbox instance 的唯一識別碼。 (Default: `自動產生`)

**sandboxName** (`string`): 傳送至 Vercel API 的選填名稱。如省略，系統會自動產生。

**token** (`string`): Vercel API token。預設改用 VERCEL\_TOKEN 環境變數。如要使用 OIDC token，請省略此項。

**teamId** (`string`): Vercel team ID。預設改用 VERCEL\_TEAM\_ID 環境變數。

**projectId** (`string`): Vercel project ID。預設改用 VERCEL\_PROJECT\_ID 環境變數。

**runtime** (`'node24' | 'node22' | 'node26' | 'python3.13'`): Sandbox runtime。 (Default: `'node24'`)

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

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

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

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

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

**instructions** (`string | ((opts) => string)`): 覆寫 getInstructions() 傳回的預設 instructions。傳入字串可取代預設內容，或傳入函式以擴充預設內容。

**onStart** (`SandboxLifecycleHook`): Sandbox 進入 running 狀態後呼叫的 lifecycle hook。

**onStop** (`SandboxLifecycleHook`): Sandbox 停止前呼叫的 lifecycle hook。

**onDestroy** (`SandboxLifecycleHook`): Sandbox 被銷毀前呼叫的 lifecycle hook。

## 屬性

**id** (`string`): Sandbox instance 識別碼。

**name** (`'VercelSandbox'`): 供人閱讀的名稱。

**provider** (`'vercel-sandbox'`): Provider 類型識別碼。

**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

**sandbox** (`Sandbox`): 底層的 @vercel/sandbox Sandbox instance。如果尚未啟動 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-HK/reference/workspace/process-manager)。

> **備註:** Vercel Sandbox SDK 不會為執行中的指令提供 stdin channel，因此 `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)。