跳至主要內容

AppleContainerSandbox

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

安裝
安裝 的直接連結

npm install @mastra/apple-container

需要配備 Apple 晶片、運行 macOS 26 或更新版本的 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?:

string
= 自動產生
此 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>
由主機至容器的綁定掛載。鍵是主機路徑，值是容器路徑。

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

capDrop?:

string[]
要移除的 Linux capabilities。

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 分鐘）
預設指令逾時時間，以毫秒為單位。

deleteOnDestroy?:

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

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' },
})

綁定掛載
綁定掛載 的直接連結

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

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

綁定掛載會在建立容器時套用。主機路徑必須在 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 指向映像檔或綁定掛載所提供的路徑。亦支援可寫入的 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 擁有的容器帶有設定雜湊標籤，但與不可變的運行時選項不符，系統不會重複使用該容器，而會回報失敗。
const sandbox = new AppleContainerSandbox({ id: 'persistent-sandbox' })
await sandbox.start()

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

編輯器 Provider
編輯器 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