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

# DockerSandbox

在本機的 Docker 容器內執行指令。使用長時間運作的容器，並透過 `docker exec` 執行指令。適用於本機開發、CI/CD、隔離網絡部署，以及毋須使用雲端 Sandbox、對成本敏感的情境。介面詳情請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-HK/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 實例的唯一識別碼。用於按標籤重新連接。 (Default: `自動產生`)

**name** (`string`): 以 --name 傳給 Docker 的容器顯示名稱。\[a-zA-Z0-9\_.-] 以外的字元會以 - 取代；如結果並非以英數字元開首，系統會加上前綴。 (Default: `` Sandbox 的 `id` ``)

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

**command** (`string[]`): 容器進入點指令。必須讓容器保持運作，以便透過 exec 執行指令。 (Default: `['sleep', 'infinity']`)

**env** (`Record<string, string>`): 在容器中設定的環境變數。

**volumes** (`Record<string, string>`): 由主機至容器的繫結掛載。鍵是主機路徑，值是容器路徑。

**network** (`string`): 要加入的 Docker 網絡。

**privileged** (`boolean`): 以特權模式執行。 (Default: `false`)

**memory** (`number`): 記憶體上限（位元組）。Docker 將 0 視為無上限。對應 Docker HostConfig.Memory。

**memorySwap** (`number`): 記憶體加交換空間的總上限（位元組）。對應 Docker HostConfig.MemorySwap。

**cpuShares** (`number`): CPU shares 的相對權重。對應 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，然後再加入指定項目。對應 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>`): 其他容器標籤。系統必定會加入 Mastra 標籤（mastra.sandbox、mastra.sandbox.id）。

**timeout** (`number`): 預設指令逾時（毫秒）。 (Default: `300000（5 分鐘）`)

**dockerOptions** (`Docker.DockerOptions`): 直接傳遞 dockerode 連線選項，以使用自訂 socket 路徑、遠端主機或 TLS 憑證。

**instructions** (`string | function`): 自訂指示，覆寫 getInstructions() 傳回的預設指示。傳入空字串可隱藏指示。

## 屬性

**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/zh-HK/reference/workspace/process-manager)。

## 環境變數

使用 `env` 在容器層級設定環境變數。產生程序時亦可傳入每項指令的環境變數：

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

## 繫結掛載

使用 `volumes` 選項將主機目錄掛載至容器：

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

繫結掛載會在建立容器時套用。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`：在容器內安裝套件，以及寫入掛載路徑以外位置的工具可能會失敗。請為 `/tmp` 等可寫入暫存路徑加入 `tmpfs` 項目；有需要時，亦請為 `~/.npm` 等套件管理器快取掛載 tmpfs 或 volume。
- `capDrop`：移除所有 capability 會停用需要 Linux capability 的指令，包括 `ping` 及掛載操作。以 FUSE 為基礎的工具亦會停用。只重新加入工作負載所需的 capability。
- `memory`：Docker 將 `0` 視為無上限。只有不想設定記憶體上限時，才省略 `memory` 或傳入 `0`。
- `memorySwap`：Docker 的記憶體及交換空間行為取決於主機及 Docker daemon 設定。設定 `memory` 而不設定 `memorySwap` 時，Docker 預設允許使用最多為記憶體上限兩倍的交換空間。如要停用容器交換空間，請將 `memorySwap` 設為與 `memory` 相同；Docker 亦接受以 `-1` 表示無限交換空間。
- `pidsLimit`：過低的值可能令 `docker exec` 工作負載失敗，因為每項指令都會在長時間運作的容器內啟動額外程序。
- `privileged`：特權容器會繞過 capability 及保安選項控制。除非工作負載有此需要，否則請勿同時使用 `privileged: true` 與 capability 或保安選項。
- 重新連接：Sandbox ID 相符時，`DockerSandbox` 會重用現有容器；如檢查所得的 `HostConfig` 強化保安值不同，便會發出警告。請銷毀並重新建立 Sandbox，以套用已變更的強化保安選項。Docker 可能會將檢查所得的值標準化；如原有容器使用 Docker 預設交換空間行為，在重新連接時變更 `memorySwap` 可能會觸發警告。
- Docker Desktop：在 macOS 及 Windows 上，資源限制會在 Docker Desktop 虛擬機器內套用，因此分配給虛擬機器的資源可能會限制容器可取得的資源。

## 重新連接

`DockerSandbox` 可透過配對標籤，重新連接現有容器。呼叫 `start()` 時，它會檢查是否有容器的 `mastra.sandbox.id` 標籤與 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 主機或使用自訂 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/zh-HK/reference/workspace/process-manager)
- [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/sandbox)
- [LocalSandbox 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/local-sandbox)
- [E2BSandbox 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/e2b-sandbox)
- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)