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

# DockerSandbox

ローカルマシン上の Docker コンテナ内でコマンドを実行します。長時間稼働するコンテナと `docker exec` を使用します。クラウド Sandbox が不要なローカル開発、CI/CD、エアギャップ環境、コスト重視の用途に適しています。インターフェースの詳細は、[WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/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/) が動作している必要があります。

## 使用方法

Workspace に `DockerSandbox` を追加して 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: `Auto-generated`)

**name** (`string`): --name として Docker に渡すコンテナの表示名。\[a-zA-Z0-9\_.-] 以外の文字は - に置換され、先頭が英数字でない場合は接頭辞が付加されます。 (Default: `` The 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 シェアの相対的な重み。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`): コンテナ内の作業ディレクトリ。 (Default: `'/workspace'`)

**labels** (`Record<string, string>`): 追加のコンテナラベル。Mastra ラベル（mastra.sandbox、mastra.sandbox.id）は常に含まれます。

**timeout** (`number`): デフォルトのコマンドタイムアウト（ミリ秒）。 (Default: `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` を使用してコンテナ内で動作します。

```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/ja/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 を1コアに制限します。Linux capability を削除し、ルート Filesystem を読み取り専用にしたうえで、`/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 またはボリュームをマウントしてください。
- `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` ラベルを持つコンテナを検索します。見つかった場合は、次のように動作します。

- 実行中のコンテナはそのまま再利用されます。
- 停止中のコンテナは再起動されます。

```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 ホストに接続するか、カスタムソケットパスを使用します。

```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/ja/reference/workspace/process-manager)
- [WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)
- [LocalSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/local-sandbox)
- [E2BSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/e2b-sandbox)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)