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

# E2BSandbox

分離された [E2B](https://e2b.dev) クラウド Sandbox でコマンドを実行します。クラウドストレージのマウントに対応した、安全で一時的な環境を提供します。インターフェースの詳細は、[WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)を参照してください。

## インストール

**npm**:

```bash
npm install @mastra/e2b
```

**pnpm**:

```bash
pnpm add @mastra/e2b
```

**Yarn**:

```bash
yarn add @mastra/e2b
```

**Bun**:

```bash
bun add @mastra/e2b
```

## 使用方法

Workspace に `E2BSandbox` を追加して Agent に割り当てます。

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  sandbox: new E2BSandbox({
    id: 'dev-sandbox',
    timeout: 60_000, // 60 second timeout (default: 5 minutes)
  }),
})

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

## コンストラクターパラメーター

**apiKey** (`string`): E2B API キー。未指定の場合は環境変数 E2B\_API\_KEY を使用します。

**timeout** (`number`): 実行タイムアウト（ミリ秒）。 (Default: `300000 (5 minutes)`)

**template** (`string | TemplateBuilder | function`): Sandbox テンプレートの指定。テンプレート ID 文字列、TemplateBuilder、またはデフォルトテンプレートをカスタマイズする関数を指定できます。

**env** (`Record<string, string>`): Sandbox に設定する環境変数。

**id** (`string`): この Sandbox インスタンスの一意な識別子。 (Default: `Auto-generated`)

**domain** (`string`): セルフホスト E2B のドメイン。未指定の場合は環境変数 E2B\_DOMAIN を使用します。

**apiUrl** (`string`): セルフホスト E2B の API URL。未指定の場合は環境変数 E2B\_API\_URL を使用します。

**accessToken** (`string`): 認証用のアクセストークン。未指定の場合は環境変数 E2B\_ACCESS\_TOKEN を使用します。

**metadata** (`Record<string, unknown>`): Sandbox インスタンスに付加するカスタムメタデータ。

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): getInstructions() が返すカスタム指示。文字列はデフォルトを完全に置き換えます。関数はデフォルトを受け取り、リクエストごとに拡張またはカスタマイズできます。指示をすべて非表示にするには空文字列を渡します。

## プロパティ

**id** (`string`): Sandbox インスタンスの識別子。

**name** (`string`): Provider 名（'E2BSandbox'）。

**provider** (`string`): Provider 識別子（'e2b'）。

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

**processes** (`E2BProcessManager`): バックグラウンドプロセスマネージャー。SandboxProcessManager リファレンスを参照してください。

## バックグラウンドプロセス

`E2BSandbox` には、バックグラウンドプロセスを起動・管理するプロセスマネージャーが組み込まれています。プロセスは E2B SDK の `commands.run()` に `background: true` を指定し、E2B クラウド Sandbox 内で動作します。

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

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

// Interact with the process
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()
```

E2B プロセスマネージャーは、外部または再接続前に起動されたプロセスへの再接続に対応します。既存プロセスへ接続するには、PID を指定して `get(pid)` を呼び出します。

```typescript
const handle = await sandbox.processes.get(existingPid)
if (handle) {
  console.log(handle.stdout)
}
```

完全な API は、[`SandboxProcessManager` リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/process-manager)を参照してください。

## クラウドストレージのマウント

E2B Sandbox は S3、GCS、Azure Blob の Filesystem をマウントし、クラウドストレージを Sandbox 内のローカルディレクトリとして利用できます。次の用途に便利です。

- クラウドバケットに保存された大規模データセットの処理
- クラウドストレージへの出力ファイルの直接書き込み
- Sandbox セッション間でのデータ共有

### mounts 設定を使用する

Filesystem をマウントする最も簡単な方法は、Workspace の `mounts` 設定を使用することです。

```typescript
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/s3-data': new S3Filesystem({
      bucket: 'my-s3-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
    '/gcs-data': new GCSFilesystem({
      bucket: 'my-gcs-bucket',
      projectId: 'my-project',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})
```

Sandbox の起動時に、Filesystem が指定されたパスへ自動的にマウントされます。Sandbox 内で実行されるコードは、`/s3-data` と `/gcs-data` のファイルへローカルディレクトリと同様にアクセスできます。

### マウントの仕組み

E2B Sandbox は FUSE（Filesystem in Userspace）を使用してクラウドストレージをマウントします。

- **S3/R2**：[s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) を介してマウント
- **GCS**：[gcsfuse](https://github.com/GoogleCloudPlatform/gcsfuse) を介してマウント
- **Azure Blob**：[blobfuse2](https://github.com/Azure/azure-storage-fuse) を介してマウント

E2B Sandbox は、マウントの使用時に必要な FUSE Tool を自動的にインストールします。最高のパフォーマンスを得るには、Tool をインストールしたカスタムテンプレートを事前にビルドしてください。

## カスタムテンプレート

デフォルトでは、テンプレートを指定しない場合、E2BSandbox は S3 マウント対応のため `s3fs` をインストールしたテンプレートを自動的にビルドします。このテンプレートはキャッシュされ、Sandbox インスタンス間で再利用されます。

GCS のマウントでは、`gcsfuse` が存在しない場合にマウント時に自動インストールされます。追加の Tool が必要な場合やコールドスタートを高速化する場合は、カスタムテンプレートを使用してください。

### 既存のテンプレートを使用する

ビルド済みのテンプレートがある場合は、その ID を渡します。

```typescript
const workspace = new Workspace({
  sandbox: new E2BSandbox({
    id: 'dev-sandbox',
    template: 'my-custom-template',
  }),
})
```

### デフォルトテンプレートをカスタマイズする

デフォルトのマウント対応テンプレートをカスタマイズする関数を渡します。関数は `TemplateBuilder` を受け取り、変更後のテンプレートを返す必要があります。

```typescript
const workspace = new Workspace({
  sandbox: new E2BSandbox({
    template: base =>
      base
        .aptInstall(['ffmpeg', 'imagemagick', 'poppler-utils'])
        .pipInstall(['pandas', 'numpy'])
        .npmInstall(['sharp']),
  }),
})
```

テンプレートビルダーは、次のような操作のメソッドチェーンに対応します。

- `aptInstall(packages)` - システムパッケージをインストール
- `pipInstall(packages)` - Python パッケージをインストール
- `npmInstall(packages)` - Node.js パッケージをインストール
- `runCmd(command)` - シェルコマンドを実行
- `setEnvs(vars)` - 環境変数を設定
- `copy(src, dest)` - テンプレートへファイルをコピー

利用可能なメソッドの完全な一覧は、[E2B のテンプレートドキュメント](https://e2b.dev/docs/template/defining-template)を参照してください。

### テンプレートを事前にビルドする

デフォルトテンプレートは初回使用時にビルドされ、キャッシュされます。コールドスタートを高速化する場合や GCS 対応を含める場合は、テンプレートを事前にビルドできます。

```typescript
import { createDefaultMountableTemplate } from '@mastra/e2b'
import { Template } from 'e2b'

// Get the default mountable template (includes s3fs)
const { template, id } = createDefaultMountableTemplate()

// Build and save to E2B
const result = await Template.build(template, id)
console.log('Template ID:', result.templateId)

// Use this ID in your E2BSandbox config for instant startup
const sandbox = new E2BSandbox({
  template: result.templateId,
})
```

GCS のコールドスタートを高速化するには、カスタムテンプレートへ `gcsfuse` を事前にインストールします。

```typescript
const workspace = new Workspace({
  sandbox: new E2BSandbox({
    id: 'dev-sandbox',
    template: base => base.aptInstall(['gcsfuse']),
  }),
})
```

これは任意です。`gcsfuse` が存在しない場合は、マウント時に自動インストールされます。

## Code Mode で使用する

[Code Mode](https://mastra.zisheng.pro/ja/docs/agents/code-mode) では、Agent が Tool を連携させる単一の TypeScript プログラムを記述できます。E2B はこのプログラムをリモートのマイクロ VM で実行するため、ホストではなく Sandbox の Filesystem へプログラムを書き込むトランスポートが必要です。`@mastra/e2b` は、この用途に `E2BCodeModeTransport` を提供します。`createCodeMode` の第2引数として渡してください。

```typescript
import { createCodeMode } from '@mastra/core/tools'
import { E2BSandbox, E2BCodeModeTransport } from '@mastra/e2b'

const { tool, instructions } = createCodeMode(
  {
    tools: { getWeather, getForecast },
    sandbox: new E2BSandbox({ timeout: 60_000 }),
  },
  new E2BCodeModeTransport(),
)
```

`E2BCodeModeTransport` は、Sandbox が動作していなければ自動起動し、ホスト上の esbuild で TypeScript を除去して（Sandbox の Node バージョンに関係なく動作）、VM 内で `node` を実行した後、プログラムファイルをクリーンアップします。`@mastra/core` のデフォルトの `StdioCodeModeTransport` は、`LocalSandbox` など、ホストの Filesystem を共有する Sandbox でのみ動作します。

## 関連項目

- [SandboxProcessManager リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/process-manager)
- [WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)
- [LocalSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/local-sandbox)
- [S3Filesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/s3-filesystem)
- [GCSFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/gcs-filesystem)
- [Azure Blob Filesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/azure-blob-filesystem)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)