跳到主要内容

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 dashboard 获取凭据。

构造函数参数
构造函数参数的直接链接

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() 返回的自定义 instructions。传入字符串可完全替换默认值，传入函数则可对其扩展。

onStart?:

function
Sandbox 达到 running 状态后调用的生命周期 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。如果未找到，则基于最新 snapshot（如果之前的 _stop() 生成过）或 baseImage 创建 Sandbox。
  • _stop()：为文件系统创建 snapshot，然后终止 Sandbox。snapshot 会保留在同一实例的内存中，供后续启动使用。
  • _destroy()：终止 Sandbox 并丢弃所有 snapshot。
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