Sandbox

加入版本： @mastra/core@1.1.0

Sandbox Provider 让 Agent 能够执行 shell 命令。在 Workspace 上配置 Sandbox 后，Agent 可以在任务执行过程中运行命令。

Sandbox Provider 在受控环境中执行命令：

• 命令执行：运行带参数的 shell 命令
• 后台进程：启动开发 Server 和 watcher 等长期运行的进程
• 工作目录：从特定目录运行命令
• 环境变量：控制可用变量
• 超时：防止长期运行的命令一直挂起
• 隔离：可选的操作系统级 Sandbox，提高安全性

📹 观看视频

观看 Mastra 远程 Sandbox 概述，了解远程 Sandbox 如何为 Agent 提供隔离的计算机环境。

支持的 Provider

• LocalSandbox：在本地计算机上执行命令
• AgentCoreRuntimeSandbox：在 AWS Bedrock AgentCore Runtime 会话中执行命令
• AppleContainerSandbox：使用 Apple 的 container CLI，在本地 OCI Linux 容器中执行命令
• BlaxelSandbox：在隔离的 Blaxel 云 Sandbox 中执行命令
• DaytonaSandbox：在隔离的 Daytona 云 Sandbox 中执行命令
• DockerSandbox：在本地计算机上长期运行的 Docker 容器中执行命令
• E2BSandbox：在隔离的 E2B 云 Sandbox 中执行命令
• ModalSandbox：在隔离的 Modal 云 Sandbox 中执行命令
• PlatformSandbox：在关联到 Mastra Platform 环境的 Sandbox 中执行命令
• RailwaySandbox：在临时、隔离的 Railway 云 Sandbox 中执行命令
• VercelSandbox：在临时 Vercel Sandbox Firecracker MicroVM 中执行命令
• VercelServerlessSandbox：以无状态 Vercel Serverless 函数的形式执行命令

基本用法

创建带 Sandbox 的 Workspace，并将其分配给 Agent。随后，Agent 就能执行 shell 命令：

src/mastra/agents/dev-agent.ts

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a helpful development assistant.',
  workspace,
})

// The agent now has the execute_command tool available
const response = await agent.generate('Run `ls -la` in the workspace directory')

有关环境隔离和原生操作系统 Sandbox 等配置选项，请参阅 LocalSandbox Reference。

动态 Sandbox

sandbox 选项接受 resolver 函数，而不只是静态实例。Resolver 接收 requestContext，并为每个请求返回 Sandbox，使单个 Workspace 能够根据调用方的身份、角色或租户提供不同的 Sandbox。

src/mastra/workspaces.ts

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  sandbox: ({ requestContext }) => {
    const userId = requestContext.get('user-id') as string
    return new LocalSandbox({
      workingDirectory: `/workspaces/${userId}`,
    })
  },
})

const agent = new Agent({
  id: 'multi-tenant-agent',
  model: 'your-provider/your-model',
  workspace,
})

每个请求都会在 Tool 执行时解析自己的 Sandbox：

import { RequestContext } from '@mastra/core/request-context'

// User Alice — commands run in /workspaces/alice
const aliceCtx = new RequestContext([['user-id', 'alice']])
await agent.generate('List files in cwd', { requestContext: aliceCtx })

// User Bob — commands run in /workspaces/bob
const bobCtx = new RequestContext([['user-id', 'bob']])
await agent.generate('List files in cwd', { requestContext: bobCtx })

默认情况下，Workspace 指令会使用稳定的占位文本描述运行时 Sandbox。如需包含每个请求的具体详情，请参阅 Workspace 指令。

Resolver 也可以是异步函数，例如从数据库查找租户配置：

const workspace = new Workspace({
  sandbox: async ({ requestContext }) => {
    const tenant = await db.getTenant(requestContext.get('tenant-id'))
    return new LocalSandbox({ workingDirectory: tenant.workspacePath })
  },
})

生命周期所有权

Sandbox 为静态实例时，workspace.init() 会调用其 start() 方法，workspace.destroy() 会调用其 destroy() 方法。使用 resolver 时，Workspace 在构造时没有可管理的实例，因此返回 Sandbox 的生命周期由调用方负责。

Resolver 必须返回可立即使用的 Sandbox：它可以已经启动，也可以无需显式启动即可处理调用。调用方还负责决定何时清理返回的 Sandbox。

可以按请求、租户或用户进行清理，也可以将其作为长期 Sandbox 池的一部分。workspace.destroy() 不会销毁 resolver 返回的 Sandbox。

备注

sandbox resolver 与 mounts 和 lsp: true 不兼容。二者都要求在构造时提供具体 Sandbox 实例，因此与 resolver 组合时，会抛出 INVALID_CONFIG 错误（对于 mounts），或在显示警告后禁用 LSP（对于 lsp: true）。

Tool 注册

使用静态 Sandbox 时，Workspace 会检查实例，决定注册哪些 Tool。使用 resolver 时，Workspace 假定它具有完整能力，并注册 execute_command（支持 background）、get_process_output 和 kill_process。如果解析后的 Sandbox 未实现某项能力，运行时会抛出清晰的 SandboxFeatureNotSupportedError。

后台进程连续性

后台进程可以在单次 Tool 调用结束后继续存在，因此 get_process_output 和 kill_process 必须访问启动该进程的同一个 Sandbox。默认情况下，解析后的 Sandbox 会按请求缓存。若要让后续请求（例如之后的对话轮次）保持连续，请将 sandboxCacheKey 设为稳定标识符。解析后的 Sandbox 将按该键缓存，而不是按请求缓存：

const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  sandboxCacheKey: ({ requestContext }) => requestContext.get('thread-id') as string,
})

如果不提供 sandboxCacheKey，对于共享租户、用户或会话的后续调用，resolver 本身必须返回同一个 Sandbox。

不再需要已缓存的 Sandbox 时，请在自己的生命周期代码中销毁它，并调用 workspace.clearSandboxCache(cacheKey) 删除 Workspace cache 条目。调用 workspace.clearSandboxCache() 可清除所有带键的 Sandbox 条目。

Workspace 指令

Workspace 指令会在 Agent 系统消息中描述环境。使用 Sandbox resolver 时，Workspace 不会调用 resolver 来构建这些指令，而是发出稳定的占位文本。这样构造 prompt 时不会预配由调用方所有的 Sandbox，系统消息也会在不同请求间保持一致，从而使 prompt cache 有效。

若要包含每个请求的具体 Sandbox 详情，请将 instructions.dynamicSandbox 设置为 'resolve'：

const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  instructions: { dynamicSandbox: 'resolve' },
})

'resolve' 会在每个请求中调用 resolver，这可能会预配 Sandbox，并使系统消息因请求而异。也可以传入函数，直接根据 requestContext 返回自定义文本，而无需解析 Sandbox：

const workspace = new Workspace({
  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
  instructions: {
    dynamicSandbox: ({ requestContext }) =>
      `Sandbox scoped to tenant ${requestContext.get('tenant-id')}.`,
  },
})

Agent Tool

在 Workspace 上配置 Sandbox 后，Agent 会获得用于运行 shell 命令的 execute_command Tool。

如果 Sandbox Provider 支持在后台运行进程，execute_command Tool 还会接受 background: true 来启动长期运行的进程，并注册另外两个 Tool：

Tool	说明
execute_command	运行 shell 命令，返回 stdout、stderr 和退出码。支持使用 background: true 启动长期运行的进程并返回 PID。
get_process_output	按 PID 获取后台进程的 stdout、stderr 和状态。支持使用 tail 限制输出行数，以及使用 wait: true 阻塞至退出。
kill_process	按 PID 停止后台进程，并返回近期输出。

这些 Tool 会自动注册。有关完整 Tool 名称列表，请参阅 Workspace 类 Reference。

后台进程回调

Agent 通过 execute_command Tool 启动后台进程时，你可以接收 stdout、stderr 和进程退出的生命周期回调。请通过 execute_command Tool 上的 backgroundProcesses 选项进行配置：

src/mastra/workspaces.ts

import { Workspace, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      backgroundProcesses: {
        onStdout: (data, { pid }) => console.log(`[${pid}] ${data}`),
        onStderr: (data, { pid }) => console.error(`[${pid}] ${data}`),
        onExit: ({ pid, exitCode }) => console.log(`Process ${pid} exited: ${exitCode}`),
      },
    },
  },
})

Agent 通过 execute_command Tool 启动的所有后台进程都会触发这些回调。

中止信号

默认情况下，后台进程会继承 Agent 的中止信号，并在 Agent 断开连接时终止。通过 abortSignal 选项控制此行为：

• undefined（默认）：使用 Agent 的中止信号
• AbortSignal：使用自定义信号
• null 或 false：禁用中止；进程会在 Agent 关闭后继续存在

src/mastra/workspaces.ts

import { Workspace, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace'

const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      backgroundProcesses: {
        abortSignal: null, // Processes survive agent disconnection
      },
    },
  },
})

对于进程应比 Agent 生命周期更长的云 Sandbox（例如 E2B、Daytona 或 Modal），请使用 null 或 false。

备注

有关完整 SandboxProcessManager API（以编程方式启动进程、读取输出以及发送 stdin），请参阅 SandboxProcessManager Reference。

相关内容

• SandboxProcessManager Reference
• AgentCoreRuntimeSandbox Reference
• AppleContainerSandbox Reference
• DaytonaSandbox Reference
• E2BSandbox Reference
• LocalSandbox Reference
• ModalSandbox Reference
• VercelSandbox Reference
• VercelServerlessSandbox Reference
• Workspace 概述
• 文件系统