DockerSandbox

在本機的 Docker 容器內執行指令。使用長時間運作的容器，並透過 docker exec 執行指令。適用於本機開發、CI/CD、隔離網絡部署，以及毋須使用雲端 Sandbox、對成本敏感的情境。介面詳情請參閱 WorkspaceSandbox 介面。

安裝

npm

npm install @mastra/docker

pnpm

pnpm add @mastra/docker

Yarn

yarn add @mastra/docker

Bun

bun add @mastra/docker

主機必須正在執行 Docker Engine。

用法

將 DockerSandbox 加入 Workspace，並指派給 Agent：

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 實例的唯一識別碼。用於按標籤重新連接。

name?:

string

= Sandbox 的 `id`

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

image?:

string

= 'node:22-slim'

容器使用的 Docker 映像檔。

command?:

string[]

= ['sleep', 'infinity']

容器進入點指令。必須讓容器保持運作，以便透過 exec 執行指令。

env?:

Record<string, string>

在容器中設定的環境變數。

volumes?:

Record<string, string>

由主機至容器的繫結掛載。鍵是主機路徑，值是容器路徑。

network?:

string

要加入的 Docker 網絡。

privileged?:

boolean

= 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

= '/workspace'

容器內的工作目錄。

labels?:

Record<string, string>

其他容器標籤。系統必定會加入 Mastra 標籤（mastra.sandbox、mastra.sandbox.id）。

timeout?:

number

= 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 在容器內執行。

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 參考。

環境變數

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

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

繫結掛載

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

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 掛載為可寫入的暫存空間：

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 相符。如找到：

• 執行中的容器會直接重用。
• 已停止的容器會重新啟動。

// 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 路徑：

// 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 參考
• WorkspaceSandbox 介面
• LocalSandbox 參考
• E2BSandbox 參考
• Workspace 概覽