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

# AppleContainerSandbox

Apple の [`container`](https://github.com/apple/container) CLI を介して、ローカル OCI Linux コンテナ内でコマンドを実行します。Provider は長時間稼働するコンテナを起動し、Workspace のコマンドに `container exec` を使用します。インターフェースの詳細は、[WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)を参照してください。

## インストール

**npm**:

```bash
npm install @mastra/apple-container
```

**pnpm**:

```bash
pnpm add @mastra/apple-container
```

**Yarn**:

```bash
yarn add @mastra/apple-container
```

**Bun**:

```bash
bun add @mastra/apple-container
```

Apple シリコン搭載 Mac、macOS 26 以降、Apple の `container` CLI が必要です。Provider を使用する前にコンテナシステムを起動してください。

```bash
container system start
```

## 使用方法

Workspace に `AppleContainerSandbox` を追加して Agent に割り当てます。

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AppleContainerSandbox } from '@mastra/apple-container'

const workspace = new Workspace({
  sandbox: new AppleContainerSandbox({
    image: 'node:22-slim',
    volumes: {
      '/Users/me/project': '/workspace',
    },
    workingDir: '/workspace',
  }),
})

const agent = new Agent({
  id: 'dev-agent',
  name: 'Dev Agent',
  instructions: 'You are a coding assistant working in this workspace.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

const response = await agent.generate('Run `node --version`.')
console.log(response.text)
```

## コンストラクターパラメーター

**id** (`string`): この Sandbox インスタンスの一意な識別子。 (Default: `Auto-generated`)

**name** (`string`): container run --name に渡す Apple コンテナ名。\[a-zA-Z0-9\_.-] 以外の文字は - に置換され、先頭が英数字でない場合は接頭辞が付加されます。 (Default: `` The sandbox `id` ``)

**image** (`string`): コンテナで使用する OCI イメージ。 (Default: `'node:22-slim'`)

**command** (`string[]`): コンテナの初期化コマンド。exec ベースでコマンドを実行できるよう、コンテナを稼働状態に保つ必要があります。 (Default: `['sleep', 'infinity']`)

**env** (`Record<string, string>`): コンテナ内およびコマンド実行時に設定する環境変数。

**volumes** (`Record<string, string>`): ホストからコンテナへのバインドマウント。キーはホストパス、値はコンテナパスです。

**mounts** (`string[]`): container run --mount の未加工の指定。

**network** (`string`): Apple コンテナのネットワーク接続指定。

**publishedPorts** (`string[]`): --publish として渡すポート公開指定。

**publishedSockets** (`string[]`): --publish-socket として渡すソケット公開指定。

**cpus** (`number | string`): 割り当てる CPU 数。

**memory** (`string`): メモリ割り当て（例：'1G'）。

**platform** (`string`): OCI プラットフォーム（例：'linux/arm64'）。

**arch** (`string`): マルチアーキテクチャイメージを選択する際のイメージアーキテクチャ。

**os** (`string`): マルチプラットフォームイメージを選択する際のイメージ OS。

**rosetta** (`boolean`): コンテナ内で Rosetta を有効にするかどうか。 (Default: `false`)

**readonlyRootfs** (`boolean`): コンテナのルート Filesystem を読み取り専用でマウントするかどうか。 (Default: `false`)

**ssh** (`boolean`): ホストの SSH Agent ソケットを転送するかどうか。 (Default: `false`)

**init** (`boolean`): コンテナ内で Apple の init プロセスを有効にするかどうか。 (Default: `true`)

**virtualization** (`boolean`): コンテナに仮想化機能を公開するかどうか。 (Default: `false`)

**capAdd** (`string[]`): 追加する Linux capability。

**capDrop** (`string[]`): 削除する Linux capability。

**tmpfs** (`string[]`): --tmpfs として渡す tmpfs の宛先パス（例：/tmp）。

**dns** (`string[]`): DNS ネームサーバーの IP。

**dnsSearch** (`string[]`): DNS 検索ドメイン。

**noDns** (`boolean`): コンテナ内で DNS を設定しないかどうか。 (Default: `false`)

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

**workingDir** (`string`): コンテナ内の作業ディレクトリ。 (Default: `'/workspace'`)

**timeout** (`number`): デフォルトのコマンドタイムアウト（ミリ秒）。 (Default: `300000 (5 minutes)`)

**deleteOnDestroy** (`boolean`): Sandbox の破棄時に Apple コンテナを削除するかどうか。false の場合、代わりにコンテナを停止します。 (Default: `true`)

**containerBinary** (`string`): Apple container CLI のパスまたは名前。 (Default: `'container'`)

**instructions** (`string | function`): getInstructions() が返すデフォルトの指示を上書きするカスタム指示。指示を非表示にするには空文字列を渡します。

## プロパティ

**id** (`string`): Sandbox インスタンスの識別子。

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

**provider** (`string`): Provider 識別子（'apple-container'）。

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

**containerId** (`string`): 判明している場合は Apple コンテナ ID、それ以外は設定されたコンテナ名。

## 環境変数

コンテナレベルの環境変数は `env` で設定します。コマンドごとの環境変数は `executeCommand` のオプションでも渡せます。

```typescript
const sandbox = new AppleContainerSandbox({
  image: 'node:22-slim',
  env: {
    NODE_ENV: 'development',
  },
})

await sandbox.executeCommand('node', ['-e', 'console.log(process.env.TASK_ID)'], {
  env: { TASK_ID: '42' },
})
```

## バインドマウント

`volumes` オプションを使用して、ホストのディレクトリをコンテナにマウントします。

```typescript
const sandbox = new AppleContainerSandbox({
  image: 'node:22-slim',
  volumes: {
    '/Users/me/project': '/workspace/project',
    '/Users/me/.npm': '/root/.npm',
  },
})
```

バインドマウントはコンテナ作成時に適用されます。ホストパスは Sandbox の起動前に存在している必要があります。

## リソースとプラットフォームのオプション

Apple container CLI のオプションはコンストラクターから渡せます。

```typescript
const sandbox = new AppleContainerSandbox({
  image: 'node:22-slim',
  volumes: {
    '/Users/me/project': '/workspace',
  },
  cpus: 2,
  memory: '2G',
  platform: 'linux/arm64',
  readonlyRootfs: true,
  tmpfs: ['/tmp'],
})
```

これらのオプションは、新しいコンテナの作成時にのみ適用されます。Sandbox が同名の既存コンテナへ再接続する場合、変更したランタイムオプションを適用するには Sandbox を破棄して再作成してください。 Apple の `--tmpfs` は `/tmp` などのコンテナパスのみを受け付け、`/tmp:rw,size=256m` のような Docker 形式のオプション指定には対応していません。 `readonlyRootfs` を有効にする場合、`workingDir` がイメージまたはバインドマウントで提供されるパスを指すようにしてください。書き込み可能な tmpfs も使用できます。

## セキュリティモデル

`AppleContainerSandbox` は、ホストの Apple `container` サービスを介してローカルコンテナを実行します。コンストラクターオプションは、信頼できるサーバー側設定として扱ってください。

- `volumes`、`mounts`、`publishedSockets` は、コンテナ内のコードにホストパスを公開する可能性があります。
- `publishedPorts` は、コンテナ内のサービスをホストまたはネットワークに公開する可能性があります。ローカルアクセスのみを想定する場合は `127.0.0.1` にバインドしてください。
- `ssh` はホストの SSH Agent ソケットを転送します。
- `capAdd` と `virtualization` は、コンテナ内のコードが実行できる操作を拡大する可能性があります。
- `containerBinary` は信頼できるコード向けのコンストラクター専用エスケープハッチであり、シリアライズ可能な Editor Provider スキーマには含まれません。

ワークロードに必要な最小限のマウントと capability を使用してください。既存コンテナに再接続できるのは、その Sandbox ID に対応する Mastra の所有権ラベルが付いている場合だけです。この Provider が作成したコンテナには設定ハッシュラベルも含まれます。このラベルがある場合、イメージ、コマンド、マウント、ポート、capability、作業ディレクトリなどの変更不可のランタイムオプションが変わっていると、再接続は失敗します。

## 制限事項

`AppleContainerSandbox` は `executeCommand()` によるフォアグラウンドの Workspace コマンド実行に対応しています。バックグラウンドプロセスや LSP セッション用の `SandboxProcessManager` はまだ公開していません。

コマンドのタイムアウトはコンテナ内で適用されるため、タイムアウトしたコマンドはコンテナランタイムによってクリーンアップされます。中断シグナルはホスト CLI の待機処理を取り消すだけです。コンテナ内のクリーンアップが重要な場合、コマンドタイムアウトの代わりに使用しないでください。

## 再接続

`AppleContainerSandbox` は、設定された名前のコンテナを調べて再接続します。`start()` の呼び出し時には、次のように動作します。

- 実行中のコンテナは再利用されます。
- 停止中のコンテナは再起動されます。
- コンテナが存在しない場合は、設定されたイメージから作成されます。
- 設定された名前のコンテナに対応する Mastra の所有権ラベルがない場合は、管理せずに失敗します。
- Mastra が所有するコンテナでも、設定ハッシュラベルが変更不可のランタイムオプションと一致しない場合は、再利用せずに失敗します。

```typescript
const sandbox = new AppleContainerSandbox({ id: 'persistent-sandbox' })
await sandbox.start()

const sandbox2 = new AppleContainerSandbox({ id: 'persistent-sandbox' })
await sandbox2.start()
```

## Editor Provider への登録

保存された Sandbox 設定を復元できるよう、Provider を `MastraEditor` に登録します。

```typescript
import { MastraEditor } from '@mastra/editor'
import { appleContainerSandboxProvider } from '@mastra/apple-container'

const editor = new MastraEditor({
  sandboxes: {
    [appleContainerSandboxProvider.id]: appleContainerSandboxProvider,
  },
})
```

## 関連項目

- [WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)
- [DockerSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/docker-sandbox)
- [LocalSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/local-sandbox)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)