AppleContainerSandbox
Apple の container CLI を介して、ローカル OCI Linux コンテナ内でコマンドを実行します。Provider は長時間稼働するコンテナを起動し、Workspace のコマンドに container exec を使用します。インターフェースの詳細は、WorkspaceSandbox インターフェースを参照してください。
インストールインストールへの直接リンク
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/apple-container
pnpm add @mastra/apple-container
yarn add @mastra/apple-container
bun add @mastra/apple-container
Apple シリコン搭載 Mac、macOS 26 以降、Apple の container CLI が必要です。Provider を使用する前にコンテナシステムを起動してください。
container system start
使用方法使用方法への直接リンク
Workspace に AppleContainerSandbox を追加して Agent に割り当てます。
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?:
name?:
container run --name に渡す Apple コンテナ名。[a-zA-Z0-9_.-] 以外の文字は - に置換され、先頭が英数字でない場合は接頭辞が付加されます。image?:
command?:
env?:
volumes?:
mounts?:
container run --mount の未加工の指定。network?:
publishedPorts?:
--publish として渡すポート公開指定。publishedSockets?:
--publish-socket として渡すソケット公開指定。cpus?:
memory?:
platform?:
arch?:
os?:
rosetta?:
readonlyRootfs?:
ssh?:
init?:
virtualization?:
capAdd?:
capDrop?:
tmpfs?:
--tmpfs として渡す tmpfs の宛先パス（例：/tmp）。dns?:
dnsSearch?:
noDns?:
labels?:
workingDir?:
timeout?:
deleteOnDestroy?:
containerBinary?:
instructions?:
プロパティプロパティへの直接リンク
id:
name:
provider:
status:
containerId:
環境変数環境変数への直接リンク
コンテナレベルの環境変数は env で設定します。コマンドごとの環境変数は executeCommand のオプションでも渡せます。
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 オプションを使用して、ホストのディレクトリをコンテナにマウントします。
const sandbox = new AppleContainerSandbox({
image: 'node:22-slim',
volumes: {
'/Users/me/project': '/workspace/project',
'/Users/me/.npm': '/root/.npm',
},
})
バインドマウントはコンテナ作成時に適用されます。ホストパスは Sandbox の起動前に存在している必要があります。
リソースとプラットフォームのオプションリソースとプラットフォームのオプションへの直接リンク
Apple container CLI のオプションはコンストラクターから渡せます。
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 が所有するコンテナでも、設定ハッシュラベルが変更不可のランタイムオプションと一致しない場合は、再利用せずに失敗します。
const sandbox = new AppleContainerSandbox({ id: 'persistent-sandbox' })
await sandbox.start()
const sandbox2 = new AppleContainerSandbox({ id: 'persistent-sandbox' })
await sandbox2.start()
Editor Provider への登録Editor Provider への登録への直接リンク
保存された Sandbox 設定を復元できるよう、Provider を MastraEditor に登録します。
import { MastraEditor } from '@mastra/editor'
import { appleContainerSandboxProvider } from '@mastra/apple-container'
const editor = new MastraEditor({
sandboxes: {
[appleContainerSandboxProvider.id]: appleContainerSandboxProvider,
},
})