> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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/reference/workspace/sandbox)。

> **备注:** 它不同于 [`VercelServerlessSandbox`](https://mastra.zisheng.pro/reference/workspace/vercel-serverless)，后者会以无状态 Vercel serverless **Function** 的形式运行命令。`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 上，身份验证会自动处理，无需配置。

**访问令牌（.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 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 域名。

**env** (`Record<string, string>`): 所有命令继承的默认环境变量。 (Default: `{}`)

**metadata** (`Record<string, unknown>`): 通过 getInfo() 呈现的自定义元数据。 (Default: `{}`)

**instructions** (`string | ((opts) => string)`): 覆盖 getInstructions() 返回的默认指令。传入字符串可替换默认指令，传入函数则可扩展默认值。

**onStart** (`SandboxLifecycleHook`): Sandbox 达到 running 状态后调用的 lifecycle hook。

**onStop** (`SandboxLifecycleHook`): Sandbox 停止前调用的 lifecycle hook。

**onDestroy** (`SandboxLifecycleHook`): Sandbox 销毁前调用的 lifecycle 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` 包含用于生成和管理后台进程的进程管理器。每个生成的进程都以 detached command 的形式在 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/reference/workspace/process-manager)。

> **备注:** Vercel Sandbox SDK 不会为正在运行的命令公开 stdin channel，因此 `handle.sendStdin()` 会抛出错误。此 Provider 也不支持文件系统挂载（FUSE）。

## 限制

- 最多 32 个 vCPU，每个 vCPU 配备 2048 MB 内存。
- 最多暴露 15 个端口。
- 文件系统是临时的。它只在会话期间持久保留，并会在 Sandbox 停止时丢失。
- 最大 runtime 取决于套餐（Hobby 为 45 分钟，Pro 和 Enterprise 最长 24 小时），默认为 5 分钟。

有关当前限制和价格，请参阅 [Vercel Sandbox 文档](https://vercel.com/docs/vercel-sandbox)。