E2BSandbox
分離された E2B クラウド Sandbox でコマンドを実行します。クラウドストレージのマウントに対応した、安全で一時的な環境を提供します。インターフェースの詳細は、WorkspaceSandbox インターフェースを参照してください。
インストールインストールへの直接リンク
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/e2b
pnpm add @mastra/e2b
yarn add @mastra/e2b
bun add @mastra/e2b
使用方法使用方法への直接リンク
Workspace に E2BSandbox を追加して Agent に割り当てます。
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?:
timeout?:
template?:
env?:
id?:
domain?:
apiUrl?:
accessToken?:
metadata?:
instructions?:
getInstructions() が返すカスタム指示。文字列はデフォルトを完全に置き換えます。関数はデフォルトを受け取り、リクエストごとに拡張またはカスタマイズできます。指示をすべて非表示にするには空文字列を渡します。プロパティプロパティへの直接リンク
id:
name:
provider:
status:
processes:
バックグラウンドプロセスバックグラウンドプロセスへの直接リンク
E2BSandbox には、バックグラウンドプロセスを起動・管理するプロセスマネージャーが組み込まれています。プロセスは E2B SDK の commands.run() に background: true を指定し、E2B クラウド Sandbox 内で動作します。
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) を呼び出します。
const handle = await sandbox.processes.get(existingPid)
if (handle) {
console.log(handle.stdout)
}
完全な API は、SandboxProcessManager リファレンスを参照してください。
クラウドストレージのマウントクラウドストレージのマウントへの直接リンク
E2B Sandbox は S3、GCS、Azure Blob の Filesystem をマウントし、クラウドストレージを Sandbox 内のローカルディレクトリとして利用できます。次の用途に便利です。
- クラウドバケットに保存された大規模データセットの処理
- クラウドストレージへの出力ファイルの直接書き込み
- Sandbox セッション間でのデータ共有
mounts 設定を使用するmounts 設定を使用するへの直接リンク
Filesystem をマウントする最も簡単な方法は、Workspace の mounts 設定を使用することです。
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）を使用してクラウドストレージをマウントします。
E2B Sandbox は、マウントの使用時に必要な FUSE Tool を自動的にインストールします。最高のパフォーマンスを得るには、Tool をインストールしたカスタムテンプレートを事前にビルドしてください。
カスタムテンプレートカスタムテンプレートへの直接リンク
デフォルトでは、テンプレートを指定しない場合、E2BSandbox は S3 マウント対応のため s3fs をインストールしたテンプレートを自動的にビルドします。このテンプレートはキャッシュされ、Sandbox インスタンス間で再利用されます。
GCS のマウントでは、gcsfuse が存在しない場合にマウント時に自動インストールされます。追加の Tool が必要な場合やコールドスタートを高速化する場合は、カスタムテンプレートを使用してください。
既存のテンプレートを使用する既存のテンプレートを使用するへの直接リンク
ビルド済みのテンプレートがある場合は、その ID を渡します。
const workspace = new Workspace({
sandbox: new E2BSandbox({
id: 'dev-sandbox',
template: 'my-custom-template',
}),
})
デフォルトテンプレートをカスタマイズするデフォルトテンプレートをカスタマイズするへの直接リンク
デフォルトのマウント対応テンプレートをカスタマイズする関数を渡します。関数は TemplateBuilder を受け取り、変更後のテンプレートを返す必要があります。
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 のテンプレートドキュメントを参照してください。
テンプレートを事前にビルドするテンプレートを事前にビルドするへの直接リンク
デフォルトテンプレートは初回使用時にビルドされ、キャッシュされます。コールドスタートを高速化する場合や GCS 対応を含める場合は、テンプレートを事前にビルドできます。
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 を事前にインストールします。
const workspace = new Workspace({
sandbox: new E2BSandbox({
id: 'dev-sandbox',
template: base => base.aptInstall(['gcsfuse']),
}),
})
これは任意です。gcsfuse が存在しない場合は、マウント時に自動インストールされます。
Code Mode で使用するCode Mode で使用するへの直接リンク
Code Mode では、Agent が Tool を連携させる単一の TypeScript プログラムを記述できます。E2B はこのプログラムをリモートのマイクロ VM で実行するため、ホストではなく Sandbox の Filesystem へプログラムを書き込むトランスポートが必要です。@mastra/e2b は、この用途に E2BCodeModeTransport を提供します。createCodeMode の第2引数として渡してください。
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 でのみ動作します。