DockerSandbox

ローカルマシン上の Docker コンテナ内でコマンドを実行します。長時間稼働するコンテナと docker exec を使用します。クラウド Sandbox が不要なローカル開発、CI/CD、エアギャップ環境、コスト重視の用途に適しています。インターフェースの詳細は、WorkspaceSandbox インターフェースを参照してください。

インストール

npm

npm install @mastra/docker

pnpm

pnpm add @mastra/docker

Yarn

yarn add @mastra/docker

Bun

bun add @mastra/docker

ホストマシンで Docker Engine が動作している必要があります。

使用方法

Workspace に DockerSandbox を追加して 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

= Auto-generated

この Sandbox インスタンスの一意な識別子。ラベルベースの再接続に使用します。

name?:

string

= The 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 シェアの相対的な重み。Docker HostConfig.CpuShares に対応します。

cpuQuota?:

number

期間ごとの CPU クォータ（マイクロ秒）。Docker HostConfig.CpuQuota に対応します。

cpuPeriod?:

number

CPU の期間（マイクロ秒）。Docker HostConfig.CpuPeriod に対応します。

pidsLimit?:

number

コンテナ内のプロセス ID の最大数。Docker HostConfig.PidsLimit に対応します。

readonlyRootfs?:

boolean

コンテナのルート Filesystem を読み取り専用でマウントします。Docker HostConfig.ReadonlyRootfs に対応します。

capDrop?:

string[]

削除する Linux capability。特定の capability を追加し直す前にすべて削除するには ['ALL'] を使用します。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 minutes)

デフォルトのコマンドタイムアウト（ミリ秒）。

dockerOptions?:

Docker.DockerOptions

カスタムソケットパス、リモートホスト、TLS 証明書向けにそのまま渡す dockerode 接続オプション。

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 を1コアに制限します。Linux capability を削除し、ルート Filesystem を読み取り専用にしたうえで、/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：コンテナ内でのパッケージインストールや、マウント済みパスの外部へ書き込む Tool は失敗することがあります。/tmp などの書き込み可能な作業パスには tmpfs エントリを追加し、必要に応じて ~/.npm などのパッケージマネージャーキャッシュ用に tmpfs またはボリュームをマウントしてください。
• capDrop：すべての capability を削除すると、ping やマウント操作など、Linux capability が必要なコマンドは無効になります。FUSE ベースの Tool も無効になります。ワークロードに必要な capability だけを追加し直してください。
• memory：Docker は 0 を無制限として扱います。メモリ上限が不要な場合にのみ memory を省略するか 0 を渡してください。
• memorySwap：Docker のメモリとスワップの動作は、ホストと Docker デーモンの設定によって異なります。memorySwap なしで memory を設定すると、Docker はデフォルトでメモリ上限の2倍までスワップを許可します。コンテナのスワップを無効にするには、memorySwap を memory と同じ値に設定してください。無制限のスワップには -1 も指定できます。
• pidsLimit：各コマンドが長時間稼働するコンテナ内で追加プロセスを起動するため、値が小さすぎると docker exec のワークロードが動作しなくなることがあります。
• privileged：特権コンテナは capability とセキュリティオプションの制御を迂回します。ワークロードで必要な場合を除き、privileged: true を capability やセキュリティオプションと併用しないでください。
• 再接続：DockerSandbox は Sandbox ID が一致すると既存コンテナを再利用し、調査した HostConfig のハードニング値が異なる場合は警告します。変更したハードニングオプションを適用するには、Sandbox を破棄して再作成してください。Docker は調査時の値を正規化することがあります。また、元のコンテナで Docker のデフォルトのスワップ動作を使用していた場合、再接続時に memorySwap を変更すると警告が表示されることがあります。
• Docker Desktop：macOS と Windows では、リソース上限が Docker Desktop 仮想マシン内で適用されるため、VM に割り当てられたリソースがコンテナへの割り当て上限になります。

再接続

DockerSandbox はラベルの一致により既存コンテナへ再接続できます。start() の呼び出し時に、Sandbox ID と一致する mastra.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 ホストに接続するか、カスタムソケットパスを使用します。

// 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 の概要