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

# ModalSandbox

分離された [Modal](https://modal.com) クラウド Sandbox でコマンドを実行します。Modal のインフラストラクチャを基盤とする、安全で一時的な環境を提供します。インターフェースの詳細は、[WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/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
```

## 使用方法

Workspace に `ModalSandbox` を追加して 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() 呼び出し時に Sandbox へ再接続できるようにします。 (Default: `Auto-generated`)

**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 minutes)`)

**env** (`Record<string, string>`): 作成時に Sandbox へ組み込む環境変数。

**workdir** (`string`): Sandbox 内のデフォルト作業ディレクトリ。

**tokenId** (`string`): Modal トークン ID。未指定の場合は環境変数 MODAL\_TOKEN\_ID を使用します。

**tokenSecret** (`string`): Modal トークンシークレット。未指定の場合は環境変数 MODAL\_TOKEN\_SECRET を使用します。

**instructions** (`string | function`): getInstructions() が返すカスタム指示。デフォルトを完全に置き換えるには文字列を、拡張するには関数を渡します。

**onStart** (`function`): Sandbox が実行中のステータスになった後に呼び出すライフサイクルフック。

**onStop** (`function`): Sandbox の停止前に呼び出すライフサイクルフック。

**onDestroy** (`function`): Sandbox の破棄前に呼び出すライフサイクルフック。

## プロパティ

**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()`**：Filesystem のスナップショットを作成してから 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/ja/reference/workspace/process-manager)を参照してください。

## 関連項目

- [SandboxProcessManager リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/process-manager)
- [WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)
- [E2BSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/e2b-sandbox)
- [DaytonaSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/daytona-sandbox)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)