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

# ModalSandbox

在隔離的 [Modal](https://modal.com) 雲端 Sandbox 中執行指令。提供由 Modal 基礎設施支援的安全暫存環境。介面詳情請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-TW/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 儀表板](https://modal.com/settings/tokens)取得憑證。

## 建構函式參數

**id** (`string`): 此 Sandbox 的唯一識別碼／名稱。用作 Modal Sandbox 名稱，以便後續呼叫 start() 時可重新連線。 (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() 回傳的自訂指示。傳入字串可完全取代預設指示，傳入函式則可擴充預設指示。

**onStart** (`function`): 在 Sandbox 進入執行中狀態後呼叫的生命週期 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。如果找不到，則從最新的快照（如果之前的 `_stop()` 有可用快照）或 baseImage 建立 Sandbox。
- **`_stop()`**：建立檔案系統快照，然後終止 Sandbox。快照會保留在同一執行個體的記憶體中，供未來啟動時使用。
- **`_destroy()`**：終止 Sandbox 並捨棄所有快照。

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

## 相關內容

- [SandboxProcessManager 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/process-manager)
- [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/sandbox)
- [E2BSandbox 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/e2b-sandbox)
- [DaytonaSandbox 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/daytona-sandbox)
- [Workspace 概觀](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)