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

# AppleContainerSandbox

透過 Apple 的 [`container`](https://github.com/apple/container) CLI，在本機 OCI Linux 容器內執行指令。此 Provider 會啟動一個長時間運行的容器，並使用 `container exec` 執行 Workspace 指令。介面詳情請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-HK/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 或更新版本的 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>`): 由主機至容器的綁定掛載。鍵是主機路徑，值是容器路徑。

**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 capabilities。

**capDrop** (`string[]`): 要移除的 Linux capabilities。

**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` 選項將主機目錄掛載至容器：

```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 socket。
- `capAdd` 及 `virtualization` 可擴大容器化程式碼可執行的操作。
- `containerBinary` 是僅供受信任程式碼使用的建構函數逃生通道，不屬於可序列化的編輯器 Provider schema。

請只使用工作負載所需的最少掛載及 capabilities。只有帶有該 Sandbox ID 的 Mastra 擁有權標籤時，才會重新連接現有容器。此 Provider 建立的容器亦包括設定雜湊標籤；如該標籤存在，當映像檔、指令、掛載、連接埠、capabilities 或工作目錄等不可變的運行時選項有所變更，重新連接便會失敗。

## 限制

`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()
```

## 編輯器 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-HK/reference/workspace/sandbox)
- [DockerSandbox 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/docker-sandbox)
- [LocalSandbox 參考](https://mastra.zisheng.pro/zh-HK/reference/workspace/local-sandbox)
- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)