跳至主要內容

ModalSandbox

在隔離的 Modal 雲端 Sandbox 中執行指令。提供由 Modal 基礎設施支援的安全、暫時性環境。有關介面詳情，請參閱 WorkspaceSandbox 介面。

安裝
安裝 的直接連結

npm install @mastra/modal

用法
用法 的直接連結

將 ModalSandbox 加入 Workspace，並指派給 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
= 自動產生
此 Sandbox 的唯一識別碼／名稱。會用作 Modal Sandbox 名稱，讓後續呼叫 start() 時可重新連線至該 Sandbox。

appName?:

string
= 'mastra'
與 Sandbox 關聯的 Modal App 名稱。

baseImage?:

string
= 'ubuntu:22.04'
Sandbox 使用的 Docker 映像。

timeoutMs?:

number
= 300000（5 分鐘）
以毫秒為單位的最長實際運行時間。無論是否仍有活動，期限屆滿時都會終止 Sandbox。Modal 的上限為 24 小時（86_400_000）。

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 生命週期
Sandbox 生命週期 的直接連結

  • _start()：嘗試重新連線至現有且正在運行的 Sandbox。若找不到，則從最新快照（如先前的 _stop() 有建立快照）或 baseImage 建立 Sandbox。
  • _stop()：建立檔案系統快照，然後終止 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