跳至主要內容

AppleContainerSandbox

透過 Apple 的 container CLI，在本機 OCI Linux 容器內執行指令。此 Provider 會啟動長時間執行的容器，並使用 container exec 執行 Workspace 指令。介面詳情請參閱 WorkspaceSandbox 介面。

安裝
「安裝」的直接連結

npm install @mastra/apple-container

需要搭載 Apple 晶片、執行 macOS 26 或更新版本，且已安裝 Apple container CLI 的 Mac。使用此 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?:

string
= Auto-generated
此 Sandbox 執行個體的唯一識別碼。

name?:

string
= Sandbox 的 `id`
傳遞給 container run --name 的 Apple 容器名稱。[a-zA-Z0-9_.-] 以外的字元會替換為 -；如果結果並非以英數字元開頭，則會加上前綴。

image?:

string
= 'node:22-slim'
容器要使用的 OCI 映像檔。

command?:

string[]
= ['sleep', 'infinity']
容器初始化指令。必須讓容器持續執行，才能透過 exec 執行指令。

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
= false
在容器中啟用 Rosetta。

readonlyRootfs?:

boolean
= false
以唯讀方式掛載容器根檔案系統。

ssh?:

boolean
= false
轉送主機的 SSH Agent Socket。

init?:

boolean
= true
在容器中啟用 Apple 的 init 處理程序。

virtualization?:

boolean
= false
向容器公開虛擬化功能。

capAdd?:

string[]
要新增的 Linux capability。

capDrop?:

string[]
要移除的 Linux capability。

tmpfs?:

string[]
以 --tmpfs 傳遞的 tmpfs 目的地路徑，例如 /tmp。

dns?:

string[]
DNS 名稱伺服器 IP。

dnsSearch?:

string[]
DNS 搜尋網域。

noDns?:

boolean
= false
不要在容器中設定 DNS。

labels?:

Record<string, string>
其他容器標籤。一律包含 Mastra 標籤（mastra.sandbox、mastra.sandbox.id）。

workingDir?:

string
= '/workspace'
容器內的工作目錄。

timeout?:

number
= 300000 (5 minutes)
預設指令逾時時間，單位為毫秒。

deleteOnDestroy?:

boolean
= true
銷毀 Sandbox 時刪除 Apple 容器。若為 false，銷毀時只會停止容器。

containerBinary?:

string
= 'container'
Apple container CLI 的路徑或名稱。

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 選項傳入個別指令的環境變數：

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
「Bind mount」的直接連結

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

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 選項可以透過建構函式傳入：

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 標籤，但與不可變的執行階段選項不符，操作會失敗，而不會重複使用該容器。
const sandbox = new AppleContainerSandbox({ id: 'persistent-sandbox' })
await sandbox.start()

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

Editor Provider
「Editor Provider」的直接連結

向 MastraEditor 註冊此 Provider，以載入已儲存的 Sandbox 設定：

import { MastraEditor } from '@mastra/editor'
import { appleContainerSandboxProvider } from '@mastra/apple-container'

const editor = new MastraEditor({
  sandboxes: {
    [appleContainerSandboxProvider.id]: appleContainerSandboxProvider,
  },
})
On this page