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

# DockerSandbox

在本机的 Docker 容器中执行命令。使用长期运行的容器，并通过 `docker exec` 执行命令。适用于本地开发、CI/CD、隔离网络部署，以及无需云端 Sandbox、对成本敏感的场景。有关接口详情，请参阅 [WorkspaceSandbox 接口](https://mastra.zisheng.pro/reference/workspace/sandbox)。

## 安装

**npm**:

```bash
npm install @mastra/docker
```

**pnpm**:

```bash
pnpm add @mastra/docker
```

**Yarn**:

```bash
yarn add @mastra/docker
```

**Bun**:

```bash
bun add @mastra/docker
```

要求宿主机上运行 [Docker Engine](https://docs.docker.com/engine/install/)。

## 用法

将 `DockerSandbox` 添加到 Workspace，并将其分配给 Agent：

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { DockerSandbox } from '@mastra/docker'

const workspace = new Workspace({
  sandbox: new DockerSandbox({
    image: 'node:22-slim',
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  name: 'dev-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

## 构造函数参数

**id** (`string`): 此 Sandbox 实例的唯一标识符。用于基于 label 重新连接。 (Default: `自动生成`)

**name** (`string`): 通过 --name 传给 Docker 的容器显示名称。\[a-zA-Z0-9\_.-] 之外的字符会替换为 -；如果结果不是以字母或数字开头，则会为其添加前缀。 (Default: `` Sandbox 的 `id` ``)

**image** (`string`): 容器使用的 Docker 镜像。 (Default: `'node:22-slim'`)

**command** (`string[]`): 容器 entrypoint 命令。必须让容器持续运行，以便通过 exec 执行命令。 (Default: `['sleep', 'infinity']`)

**env** (`Record<string, string>`): 要在容器中设置的环境变量。

**volumes** (`Record<string, string>`): 宿主到容器的 bind mount。key 是宿主路径，value 是容器路径。

**network** (`string`): 要加入的 Docker 网络。

**privileged** (`boolean`): 以 privileged 模式运行。 (Default: `false`)

**memory** (`number`): 以字节为单位的内存限制。Docker 将 0 视为无限制。映射到 Docker HostConfig.Memory。

**memorySwap** (`number`): 以字节为单位的内存加 swap 总量。映射到 Docker HostConfig.MemorySwap。

**cpuShares** (`number`): CPU 份额的相对权重。映射到 Docker HostConfig.CpuShares。

**cpuQuota** (`number`): 每个周期内以微秒为单位的 CPU 配额。映射到 Docker HostConfig.CpuQuota。

**cpuPeriod** (`number`): 以微秒为单位的 CPU 周期。映射到 Docker HostConfig.CpuPeriod。

**pidsLimit** (`number`): 容器中的最大进程 ID 数量。映射到 Docker HostConfig.PidsLimit。

**readonlyRootfs** (`boolean`): 以只读方式挂载容器根文件系统。映射到 Docker HostConfig.ReadonlyRootfs。

**capDrop** (`string[]`): 要移除的 Linux capability。使用 \['ALL'] 可先移除所有 capability，再添加特定 capability。映射到 Docker HostConfig.CapDrop。

**capAdd** (`string[]`): 移除后要重新添加的 Linux capability，例如 NET\_BIND\_SERVICE。映射到 Docker HostConfig.CapAdd。

**securityOpt** (`string[]`): Docker 安全选项，例如 \['no-new-privileges:true']。映射到 Docker HostConfig.SecurityOpt。

**ulimits** (`Array<{ name: string; soft: number; hard: number }>`): 容器的 ulimit 条目。映射到 Docker HostConfig.Ulimits。

**tmpfs** (`Record<string, string>`): tmpfs 挂载路径和选项。映射到 Docker HostConfig.Tmpfs。

**workingDir** (`string`): 容器内的工作目录。 (Default: `'/workspace'`)

**labels** (`Record<string, string>`): 额外的容器 label。始终包含 Mastra label（mastra.sandbox、mastra.sandbox.id）。

**timeout** (`number`): 以毫秒为单位的默认命令超时时间。 (Default: `300000（5 分钟）`)

**dockerOptions** (`Docker.DockerOptions`): 直接传递 dockerode 连接选项，用于自定义 socket 路径、远程 host 或 TLS 证书。

**instructions** (`string | function`): 覆盖 getInstructions() 所返回默认 instructions 的自定义 instructions。传入空字符串可禁止 instructions。

## 属性

**id** (`string`): Sandbox 实例标识符。

**name** (`string`): Provider 名称（'DockerSandbox'）。

**provider** (`string`): Provider 标识符（'docker'）。

**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'

**container** (`Container`): 底层 dockerode Container 实例。如果 Sandbox 尚未启动，则抛出 SandboxNotReadyError。

**processes** (`DockerProcessManager`): 后台进程管理器。请参阅 SandboxProcessManager 参考。

## 后台进程

`DockerSandbox` 内置了用于生成和管理后台进程的进程管理器。进程使用 `docker exec` 在容器内运行。

```typescript
const sandbox = new DockerSandbox({ id: 'dev-sandbox' })
await sandbox._start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

// Interact with the process
console.log(handle.stdout)
await handle.sendStdin('input\n')
await handle.kill()
```

有关完整 API，请参阅 [`SandboxProcessManager` 参考](https://mastra.zisheng.pro/reference/workspace/process-manager)。

## 环境变量

使用 `env` 在容器级别设置环境变量。生成进程时也可以传入每个命令专属的环境变量：

```typescript
const sandbox = new DockerSandbox({
  image: 'node:22-slim',
  env: {
    NODE_ENV: 'production',
    DATABASE_URL: 'postgres://localhost:5432/mydb',
  },
})
```

## Bind mount

使用 `volumes` 选项将宿主目录挂载到容器中：

```typescript
const sandbox = new DockerSandbox({
  image: 'node:22-slim',
  volumes: {
    '/my/project': '/workspace/project',
    '/shared/data': '/data',
  },
})
```

Bind mount 会在创建容器时应用。宿主路径必须在 Sandbox 启动前存在。

## 安全强化

使用 Docker 专属资源和安全强化选项来限制 Sandbox 容器。以下示例对内存和进程数量设置上限，同时通过相同的 `cpuPeriod` 和 `cpuQuota` 值将 CPU 限制为一个核心。它还会移除 Linux capability，并将根文件系统设为只读，同时把 `/tmp` 挂载为可写的临时空间：

```typescript
const sandbox = new DockerSandbox({
  image: 'node:22-slim',
  memory: 512 * 1024 * 1024,
  memorySwap: 512 * 1024 * 1024,
  cpuPeriod: 100_000,
  cpuQuota: 100_000,
  pidsLimit: 256,
  readonlyRootfs: true,
  capDrop: ['ALL'],
  capAdd: ['NET_BIND_SERVICE'],
  securityOpt: ['no-new-privileges:true'],
  ulimits: [{ name: 'nofile', soft: 1024, hard: 2048 }],
  tmpfs: {
    '/tmp': 'rw,noexec,nosuid,size=64m',
  },
})
```

这些选项会直接映射到 Docker `HostConfig` 字段，并且只有在传入时才会设置。

启用安全强化前，请考虑以下权衡：

- `readonlyRootfs`：容器内的软件包安装，以及写入挂载路径之外位置的 Tool 可能会失败。请为 `/tmp` 等可写临时路径添加 `tmpfs` 条目；如有需要，也可为 `~/.npm` 等软件包管理器缓存挂载 tmpfs 或 volume。
- `capDrop`：移除所有 capability 会禁用需要 Linux capability 的命令，包括 `ping` 和 mount 操作。基于 FUSE 的 Tool 也会被禁用。请仅重新添加工作负载需要的 capability。
- `memory`：Docker 将 `0` 视为无限制。只有在不需要内存上限时，才应省略 `memory` 或传入 `0`。
- `memorySwap`：Docker 的内存和 swap 行为取决于宿主和 Docker daemon 配置。如果设置 `memory` 而未设置 `memorySwap`，Docker 默认允许使用最多为内存限制两倍的 swap。如果要禁用容器 swap，请将 `memorySwap` 设为与 `memory` 相同的值；Docker 也接受 `-1`，表示 swap 不受限制。
- `pidsLimit`：过低的值可能会破坏 `docker exec` 工作负载，因为每个命令都会在长期运行的容器内启动额外进程。
- `privileged`：Privileged 容器会绕过 capability 和安全选项控制。除非工作负载需要，否则不要将 `privileged: true` 与 capability 或安全选项结合使用。
- 重新连接：当 Sandbox ID 匹配时，`DockerSandbox` 会复用现有容器；如果检查到的 `HostConfig` 安全强化值不同，则发出警告。要应用更改后的安全强化选项，请销毁并重新创建 Sandbox。Docker 可能会规范化检查到的值；如果原始容器采用 Docker 默认 swap 行为，重新连接时更改 `memorySwap` 可能会触发警告。
- Docker Desktop：在 macOS 和 Windows 上，资源限制应用于 Docker Desktop 虚拟机内部，因此 VM 分配的资源可能会限制容器实际可用的资源。

## 重新连接

`DockerSandbox` 可以通过匹配 label 重新连接到现有容器。调用 `start()` 时，它会检查是否存在 `mastra.sandbox.id` label 与 Sandbox ID 匹配的容器。如果找到：

- 正在运行的容器会被直接复用。
- 已停止的容器会重新启动。

```typescript
// First run — creates a new container
const sandbox = new DockerSandbox({ id: 'persistent-sandbox' })
await sandbox._start()

// Later — reconnects to the existing container
const sandbox2 = new DockerSandbox({ id: 'persistent-sandbox' })
await sandbox2._start()
```

## Docker 连接选项

通过 `dockerOptions` 连接到远程 Docker host 或使用自定义 socket 路径：

```typescript
// Remote Docker host
const sandbox = new DockerSandbox({
  dockerOptions: {
    host: '192.168.1.100',
    port: 2376,
    ca: fs.readFileSync('ca.pem'),
    cert: fs.readFileSync('cert.pem'),
    key: fs.readFileSync('key.pem'),
  },
})

// Custom socket path
const sandbox = new DockerSandbox({
  dockerOptions: {
    socketPath: '/var/run/docker.sock',
  },
})
```

## 相关内容

- [SandboxProcessManager 参考](https://mastra.zisheng.pro/reference/workspace/process-manager)
- [WorkspaceSandbox 接口](https://mastra.zisheng.pro/reference/workspace/sandbox)
- [LocalSandbox 参考](https://mastra.zisheng.pro/reference/workspace/local-sandbox)
- [E2BSandbox 参考](https://mastra.zisheng.pro/reference/workspace/e2b-sandbox)
- [Workspace 概览](https://mastra.zisheng.pro/docs/workspace/overview)