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

# ModalSandbox

在隔离的 [Modal](https://modal.com) 云端 Sandbox 中执行命令。提供由 Modal 基础设施支持的安全临时环境。有关接口详情，请参阅 [WorkspaceSandbox 接口](https://mastra.zisheng.pro/reference/workspace/sandbox)。

## 安装

**npm**:

```bash
npm install @mastra/modal
```

**pnpm**:

```bash
pnpm add @mastra/modal
```

**Yarn**:

```bash
yarn add @mastra/modal
```

**Bun**:

```bash
bun add @mastra/modal
```

## 用法

将 `ModalSandbox` 添加到 Workspace，并将其分配给 Agent：

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { ModalSandbox } from '@mastra/modal'

const workspace = new Workspace({
  sandbox: new ModalSandbox({
    id: 'dev-sandbox',
    baseImage: 'ubuntu:22.04',
    timeoutMs: 60_000,
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

## 身份验证

通过环境变量或构造函数选项设置 Modal 凭据：

```bash
MODAL_TOKEN_ID=ak-...
MODAL_TOKEN_SECRET=as-...
```

也可以直接传入凭据：

```typescript
const sandbox = new ModalSandbox({
  tokenId: process.env.MODAL_TOKEN_ID,
  tokenSecret: process.env.MODAL_TOKEN_SECRET,
})
```

请从 [Modal dashboard](https://modal.com/settings/tokens) 获取凭据。

## 构造函数参数

**id** (`string`): 此 Sandbox 的唯一标识符/名称。它会用作 Modal Sandbox 名称，以便后续调用 start() 时重新连接该 Sandbox。 (Default: `自动生成`)

**appName** (`string`): 与 Sandbox 关联的 Modal App 名称。 (Default: `'mastra'`)

**baseImage** (`string`): Sandbox 使用的 Docker 镜像。 (Default: `'ubuntu:22.04'`)

**timeoutMs** (`number`): 以毫秒为单位的最长运行时长。无论是否仍有活动，达到该时长后 Sandbox 都会终止。Modal 的上限为 24 小时（86\_400\_000）。 (Default: `300000（5 分钟）`)

**env** (`Record<string, string>`): 创建 Sandbox 时写入其中的环境变量。

**workdir** (`string`): Sandbox 内的默认工作目录。

**tokenId** (`string`): Modal token ID。未提供时使用 MODAL\_TOKEN\_ID 环境变量。

**tokenSecret** (`string`): Modal token secret。未提供时使用 MODAL\_TOKEN\_SECRET 环境变量。

**instructions** (`string | function`): 由 getInstructions() 返回的自定义 instructions。传入字符串可完全替换默认值，传入函数则可对其扩展。

**onStart** (`function`): Sandbox 达到 running 状态后调用的生命周期 hook。

**onStop** (`function`): Sandbox 停止前调用的生命周期 hook。

**onDestroy** (`function`): Sandbox 销毁前调用的生命周期 hook。

## 属性

**id** (`string`): Sandbox 实例标识符。

**name** (`string`): Provider 名称（'ModalSandbox'）

**provider** (`string`): Provider 标识符（'modal'）

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

**modal** (`Sandbox`): 底层 Modal Sandbox 实例。如果 Sandbox 尚未启动，则抛出 SandboxNotReadyError。

**processes** (`ModalProcessManager`): 后台进程管理器。请参阅 SandboxProcessManager 参考。

## Sandbox 生命周期

- **`_start()`**：尝试重新连接到现有的正在运行的 Sandbox。如果未找到，则基于最新 snapshot（如果之前的 `_stop()` 生成过）或 baseImage 创建 Sandbox。
- **`_stop()`**：为文件系统创建 snapshot，然后终止 Sandbox。snapshot 会保留在同一实例的内存中，供后续启动使用。
- **`_destroy()`**：终止 Sandbox 并丢弃所有 snapshot。

```typescript
const sandbox = new ModalSandbox({
  id: 'dev-sandbox',
  baseImage: 'ubuntu:22.04',
  timeoutMs: 300_000,
})

await sandbox._start()
await sandbox.processes.spawn('npm install')
await sandbox._stop()
await sandbox._start()
```

## 后台进程

`ModalSandbox` 内置了用于生成和管理后台进程的进程管理器。每次调用 `spawn()` 都会通过 Modal SDK 的 `Sandbox.exec()` API 创建新的 `ContainerProcess`。

```typescript
const sandbox = new ModalSandbox({ id: 'dev-sandbox' })
await sandbox._start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node script.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

// Wait for the process to complete
const result = await handle.wait()
console.log(result.exitCode)

// Kill the process
await handle.kill()
```

> **备注:** 不支持 `sendStdin()`。Modal JS SDK 不会在 `Sandbox.exec()` 上公开 stdin。

有关完整 API，请参阅 [`SandboxProcessManager` 参考](https://mastra.zisheng.pro/reference/workspace/process-manager)。

## 相关内容

- [SandboxProcessManager 参考](https://mastra.zisheng.pro/reference/workspace/process-manager)
- [WorkspaceSandbox 接口](https://mastra.zisheng.pro/reference/workspace/sandbox)
- [E2BSandbox 参考](https://mastra.zisheng.pro/reference/workspace/e2b-sandbox)
- [DaytonaSandbox 参考](https://mastra.zisheng.pro/reference/workspace/daytona-sandbox)
- [Workspace 概览](https://mastra.zisheng.pro/docs/workspace/overview)