AppleContainerSandbox
通过 Apple 的 container CLI 在本地 OCI Linux 容器中执行命令。该 Provider 会启动一个长期运行的容器，并使用 container exec 执行 Workspace 命令。有关接口的详细信息，请参阅 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
需要一台运行 macOS 26 或更高版本的 Apple 芯片 Mac，并已安装 Apple 的 container CLI。使用该 Provider 前，请先启动容器系统：
container system start
用法用法的直接链接
将 AppleContainerSandbox 添加到 Workspace 并分配给 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 选项将 Host 目录挂载到容器中：
const sandbox = new AppleContainerSandbox({
image: 'node:22-slim',
volumes: {
'/Users/me/project': '/workspace/project',
'/Users/me/.npm': '/root/.npm',
},
})
绑定挂载会在创建容器时应用。Sandbox 启动前，Host 路径必须已经存在。
资源和平台选项资源和平台选项的直接链接
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 通过 Host 上的 Apple container 服务运行本地容器。请将构造函数选项视为受信任的服务端配置：
volumes、mounts和publishedSockets可以向容器化代码开放 Host 路径。publishedPorts可以在 Host 或网络上开放容器内服务。如果只需本地访问，请绑定到127.0.0.1。ssh会转发 Host 的 SSH Agent 套接字。capAdd和virtualization可以扩展容器化代码的能力。containerBinary是仅供受信任代码使用、只能通过构造函数配置的逃生舱，不属于可序列化的 Editor Provider schema。
请仅使用工作负载所需的最小挂载和 capability。只有当现有容器带有该 Sandbox ID 的 Mastra 所有权标签时，才会重新连接。此 Provider 创建的容器还包含配置哈希标签；如果存在该标签，而镜像、命令、挂载、端口、capability 或工作目录等不可变运行时选项发生了变化，则重新连接会失败。
限制限制的直接链接
AppleContainerSandbox 使用 executeCommand() 实现前台 Workspace 命令执行。它尚未针对后台进程或 LSP 会话开放 SandboxProcessManager。
命令超时在容器内强制执行，因此超时的命令会由容器运行时清理。中止信号会取消 Host 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 ProviderEditor Provider的直接链接
向 MastraEditor 注册 Provider，以还原存储的 Sandbox 配置：
import { MastraEditor } from '@mastra/editor'
import { appleContainerSandboxProvider } from '@mastra/apple-container'
const editor = new MastraEditor({
sandboxes: {
[appleContainerSandboxProvider.id]: appleContainerSandboxProvider,
},
})