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

# AppleContainerSandbox

透過 Apple 的 [`container`](https://github.com/apple/container) CLI，在本機 OCI Linux 容器內執行指令。此 Provider 會啟動長時間執行的容器，並使用 `container exec` 執行 Workspace 指令。介面詳情請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-TW/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 晶片、執行 macOS 26 或更新版本，且已安裝 Apple `container` CLI 的 Mac。使用此 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: `Auto-generated`)

**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>`): 主機到容器的 bind mount。鍵為主機路徑，值為容器路徑。

**mounts** (`string[]`): 原始的 container run --mount 規格。

**network** (`string`): Apple 容器網路連接規格。

**publishedPorts** (`string[]`): 以 --publish 傳遞的連接埠發布規格。

**publishedSockets** (`string[]`): 以 --publish-socket 傳遞的 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`): 轉送主機的 SSH Agent Socket。 (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' },
})
```

## Bind mount

使用 `volumes` 選項將主機目錄掛載至容器：

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

Bind mount 會在建立容器時套用。主機路徑必須在 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` 指向映像檔或 bind mount 提供的路徑。也支援可寫入的 tmpfs。

## 安全模型

`AppleContainerSandbox` 透過主機的 Apple `container` 服務執行本機容器。請將建構函式選項視為受信任的伺服器端設定：

- `volumes`、`mounts` 與 `publishedSockets` 可能會將主機路徑公開給容器化程式碼。
- `publishedPorts` 可能會將容器內服務公開至主機或網路。若只打算在本機存取，請繫結至 `127.0.0.1`。
- `ssh` 會轉送主機的 SSH Agent Socket。
- `capAdd` 與 `virtualization` 可能會擴大容器化程式碼可執行的操作範圍。
- `containerBinary` 是僅供建構函式中的受信任程式碼使用的備援機制，不屬於可序列化的 Editor Provider 結構描述。

請只使用工作負載所需的最小掛載範圍與 capability。只有帶有對應 Sandbox ID 的 Mastra 擁有權標籤時，才會重新連線至現有容器。此 Provider 建立的容器還會包含 config-hash 標籤；若存在此標籤，而映像檔、指令、掛載、連接埠、capability 或工作目錄等不可變的執行階段選項已變更，重新連線就會失敗。

## 限制

`AppleContainerSandbox` 透過 `executeCommand()` 實作前景 Workspace 指令執行。目前尚未公開可供背景處理程序或 LSP 工作階段使用的 `SandboxProcessManager`。

指令逾時會在容器內強制執行，因此逾時的指令會由容器執行階段清理。中止訊號會取消主機 CLI 的等待路徑；若容器內清理很重要，不應以中止訊號取代指令逾時。

## 重新連線

`AppleContainerSandbox` 會檢查具有設定名稱的容器來重新連線。呼叫 `start()` 時：

- 執行中的容器會直接重複使用。
- 已停止的容器會重新啟動。
- 若容器不存在，則會使用設定的映像檔建立容器。
- 若容器名稱符合設定，但沒有相符的 Mastra 擁有權標籤，操作會失敗，而不會接管該容器。
- 若 Mastra 擁有的容器具有 config-hash 標籤，但與不可變的執行階段選項不符，操作會失敗，而不會重複使用該容器。

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