> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Sandbox

**加入版本：** `@mastra/core@1.1.0`

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

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

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

> **📹 观看视频:** 观看 [Mastra 远程 Sandbox 概述](https://www.youtube.com/watch?v=Ix2X-sjVXjw)，了解远程 Sandbox 如何为 Agent 提供隔离的计算机环境。

## 支持的 Provider

- [`LocalSandbox`](https://mastra.zisheng.pro/reference/workspace/local-sandbox)：在本地计算机上执行命令
- [`AgentCoreRuntimeSandbox`](https://mastra.zisheng.pro/reference/workspace/agentcore-runtime-sandbox)：在 AWS Bedrock AgentCore Runtime 会话中执行命令
- [`AppleContainerSandbox`](https://mastra.zisheng.pro/reference/workspace/apple-container-sandbox)：使用 Apple 的 `container` CLI，在本地 OCI Linux 容器中执行命令
- [`BlaxelSandbox`](https://mastra.zisheng.pro/reference/workspace/blaxel-sandbox)：在隔离的 Blaxel 云 Sandbox 中执行命令
- [`DaytonaSandbox`](https://mastra.zisheng.pro/reference/workspace/daytona-sandbox)：在隔离的 Daytona 云 Sandbox 中执行命令
- [`DockerSandbox`](https://mastra.zisheng.pro/reference/workspace/docker-sandbox)：在本地计算机上长期运行的 Docker 容器中执行命令
- [`E2BSandbox`](https://mastra.zisheng.pro/reference/workspace/e2b-sandbox)：在隔离的 E2B 云 Sandbox 中执行命令
- [`ModalSandbox`](https://mastra.zisheng.pro/reference/workspace/modal-sandbox)：在隔离的 Modal 云 Sandbox 中执行命令
- [`PlatformSandbox`](https://mastra.zisheng.pro/reference/workspace/platform-sandbox)：在关联到 Mastra Platform 环境的 Sandbox 中执行命令
- [`RailwaySandbox`](https://mastra.zisheng.pro/reference/workspace/railway-sandbox)：在临时、隔离的 Railway 云 Sandbox 中执行命令
- [`VercelSandbox`](https://mastra.zisheng.pro/reference/workspace/vercel-sandbox)：在临时 Vercel Sandbox Firecracker MicroVM 中执行命令
- [`VercelServerlessSandbox`](https://mastra.zisheng.pro/reference/workspace/vercel-serverless)：以无状态 Vercel Serverless 函数的形式执行命令

## 基本用法

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

```typescript
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](https://mastra.zisheng.pro/reference/workspace/local-sandbox)。

## 动态 Sandbox

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

```typescript
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：

```typescript
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 指令](#workspace-instructions)。

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

```typescript
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 将按该键缓存，而不是按请求缓存：

```typescript
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'`：

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

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

```typescript
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](https://mastra.zisheng.pro/reference/workspace/workspace-class)。

## 后台进程回调

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

```typescript
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 关闭后继续存在

```typescript
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](https://mastra.zisheng.pro/reference/workspace/process-manager)。

## 相关内容

- [`SandboxProcessManager` Reference](https://mastra.zisheng.pro/reference/workspace/process-manager)
- [`AgentCoreRuntimeSandbox` Reference](https://mastra.zisheng.pro/reference/workspace/agentcore-runtime-sandbox)
- [`AppleContainerSandbox` Reference](https://mastra.zisheng.pro/reference/workspace/apple-container-sandbox)
- [`DaytonaSandbox` Reference](https://mastra.zisheng.pro/reference/workspace/daytona-sandbox)
- [`E2BSandbox` Reference](https://mastra.zisheng.pro/reference/workspace/e2b-sandbox)
- [`LocalSandbox` Reference](https://mastra.zisheng.pro/reference/workspace/local-sandbox)
- [`ModalSandbox` Reference](https://mastra.zisheng.pro/reference/workspace/modal-sandbox)
- [`VercelSandbox` Reference](https://mastra.zisheng.pro/reference/workspace/vercel-sandbox)
- [`VercelServerlessSandbox` Reference](https://mastra.zisheng.pro/reference/workspace/vercel-serverless)
- [Workspace 概述](https://mastra.zisheng.pro/docs/workspace/overview)
- [文件系统](https://mastra.zisheng.pro/docs/workspace/filesystem)