メインコンテンツへ移動

ModalSandbox

分離された Modal クラウド Sandbox でコマンドを実行します。Modal のインフラストラクチャを基盤とする、安全で一時的な環境を提供します。インターフェースの詳細は、WorkspaceSandbox インターフェースを参照してください。

インストール
インストールへの直接リンク

npm install @mastra/modal

使用方法
使用方法への直接リンク

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

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 の認証情報を環境変数またはコンストラクターオプションで設定します。

MODAL_TOKEN_ID=ak-...
MODAL_TOKEN_SECRET=as-...

直接渡すこともできます。

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

認証情報は Modal ダッシュボードから取得します。

コンストラクターパラメーター
コンストラクターパラメーターへの直接リンク

id?:

string
= Auto-generated
この Sandbox の一意な識別子または名前。Modal の Sandbox 名として使用され、以後の start() 呼び出し時に Sandbox へ再接続できるようにします。

appName?:

string
= 'mastra'
Sandbox に関連付ける Modal App 名。

baseImage?:

string
= 'ubuntu:22.04'
Sandbox で使用する Docker イメージ。

timeoutMs?:

number
= 300000 (5 minutes)
実時間での最大有効期間（ミリ秒）。アクティビティに関係なく、期限が切れると Sandbox は終了します。Modal の上限は24時間（86_400_000）です。

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 のライフサイクル
Sandbox のライフサイクルへの直接リンク

  • _start()：実行中の既存 Sandbox への再接続を試みます。見つからない場合は、最新のスナップショット（以前の _stop() で作成されていれば）または baseImage から Sandbox を作成します。
  • _stop()：Filesystem のスナップショットを作成してから Sandbox を終了します。スナップショットは、以後の起動に備えて同じインスタンスのメモリ内に保持されます。
  • _destroy()：Sandbox を終了し、すべてのスナップショットを破棄します。
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 が作成されます。

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 リファレンスを参照してください。

On this page