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

# AppleContainerSandbox

通过 Apple 的 [`container`](https://github.com/apple/container) CLI 在本地 OCI Linux 容器中执行命令。该 Provider 会启动一个长期运行的容器，并使用 `container exec` 执行 Workspace 命令。有关接口的详细信息，请参阅 [WorkspaceSandbox 接口](https://mastra.zisheng.pro/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
```

需要一台运行 macOS 26 或更高版本的 Apple 芯片 Mac，并已安装 Apple 的 `container` CLI。使用该 Provider 前，请先启动容器系统：

```bash
container system start
```

## 用法

将 `AppleContainerSandbox` 添加到 Workspace 并分配给 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: `自动生成`)

**name** (`string`): 传给 container run --name 的 Apple 容器名称。不在 \[a-zA-Z0-9\_.-] 中的字符会被替换为 -；如果结果不是以字母或数字开头，还会添加前缀。 (Default: `` Sandbox 的 `id` ``)

**image** (`string`): 容器使用的 OCI 镜像。 (Default: `'node:22-slim'`)

**command** (`string[]`): 容器初始化命令。必须使容器保持运行，以便通过 exec 执行命令。 (Default: `['sleep', 'infinity']`)

**env** (`Record<string, string>`): 要在容器中和执行命令时设置的环境变量。

**volumes** (`Record<string, string>`): 从 Host 到容器的绑定挂载。键为 Host 路径，值为容器路径。

**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`): 选择多平台镜像时使用的镜像操作系统。

**rosetta** (`boolean`): 在容器中启用 Rosetta。 (Default: `false`)

**readonlyRootfs** (`boolean`): 以只读方式挂载容器根文件系统。 (Default: `false`)

**ssh** (`boolean`): 转发 Host 的 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 分钟）`)

**deleteOnDestroy** (`boolean`): 销毁 Sandbox 时删除 Apple 容器。为 false 时，destroy 会停止容器。 (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` 选项将 Host 目录挂载到容器中：

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

绑定挂载会在创建容器时应用。Sandbox 启动前，Host 路径必须已经存在。

## 资源和平台选项

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` 通过 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 所有的容器带有配置哈希标签，但该标签与不可变运行时选项不匹配，则操作会失败，而不会复用该容器。

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

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

## Editor Provider

向 `MastraEditor` 注册 Provider，以还原存储的 Sandbox 配置：

```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/reference/workspace/sandbox)
- [DockerSandbox 参考](https://mastra.zisheng.pro/reference/workspace/docker-sandbox)
- [LocalSandbox 参考](https://mastra.zisheng.pro/reference/workspace/local-sandbox)
- [Workspace 概述](https://mastra.zisheng.pro/docs/workspace/overview)