Mastra Apple Container 沙箱在 macOS 上以 OCI Linux 容器运行 Agent 工作区【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/apple-container是 Mastra 工作区体系中的一个本地沙箱 Provider它通过 Apple 官方的containerCLI在 macOS 上直接启动常驻的 OCI Linux 容器并将 MastraWorkspaceSandbox的命令执行契约映射为container exec调用。本文基于仓库中该包的 README 与源码实现完整讲解其安装方式、配置参数、生命周期与命令执行原理并给出可直接运行的代码示例帮助你为 Agent 搭建本地、隔离、可复用的 Linux 运行环境。背景为什么需要 Apple Container 沙箱Mastra 的工作区Workspace为 Agent 提供在隔离环境里执行命令、读写文件、运行进程的能力而真正干活的是各类沙箱 Provider。它们各自把 Mastra 统一的沙箱接口翻译成不同厂商的能力云端的 E2B、Modal、Vercel 微 VM自托管的 Docker以及本文的主角——本地运行的 Apple Container。Apple 开源的containerCLI 是一个原生的 OCI 容器运行时可以在 Apple Silicon Mac 上直接运行 Linux 容器无需 Docker Desktop。mastra/apple-container包正是围绕它封装出的 Provider通过container run启动一个长生命周期的 Linux 容器默认镜像node:22-slim默认命令sleep infinity保证容器不退出通过container exec在容器内逐条执行工作区命令与 MastraWorkspace、MastraSandbox抽象完全兼容接入成本极低。从 package.json 可以看到该包要求 Node.js22.13.0并以mastra/core 1.12.0-0 2.0.0-0作为 peer 依赖。安装在项目目录下安装包npm install mastra/apple-container前提条件来自 集成测试 的探测逻辑宿主机需要安装 ApplecontainerCLI且container --version能正常返回。文章后续会说明如何用集成测试验证这一前提。快速开始README 给出了最精简的接入示例构造沙箱、挂载宿主机目录、初始化工作区、执行命令、最后销毁。import { Workspace } from mastra/core/workspace; import { AppleContainerSandbox } from mastra/apple-container; const sandbox new AppleContainerSandbox({ image: node:22-slim, volumes: { /Users/me/project: /workspace, }, workingDir: /workspace, }); const workspace new Workspace({ sandbox }); await workspace.init(); const result await workspace.sandbox?.executeCommand?.(node, [--version]); console.log(result?.stdout); await workspace.destroy();示例中几个要点volumes把宿主机目录/Users/me/project以 bind mount 方式挂载到容器内/workspace让 Agent 能读写宿主机代码同时进程仍运行在隔离的 Linux 环境里workingDir指定容器内默认工作目录未设置时默认为/workspaceWorkspace.init()负责拉起沙箱workspace.destroy()在结束时销毁默认删除容器返回的result包含success、exitCode、stdout、stderr、executionTimeMs等字段。在仓库中该 Provider 的入口 src/index.ts 导出了AppleContainerSandbox、DefaultAppleContainerCommandRunner、appleContainerSandboxProvider以及一系列类型定义。完整配置参数Provider 在 provider.ts 中暴露了一份严格的configSchemaadditionalProperties: false即不接受未声明字段并且 单元测试 逐一断言了 schema 字段的精确集合。以下参数同时是AppleContainerSandboxOptions的成员定义见 sandbox/index.ts参数类型默认值说明idstring自动生成沙箱稳定标识用于重连到同一个容器namestring同id传给container run --name的容器名imagestringnode:22-slim使用的 OCI 镜像commandstring[][sleep,infinity]容器 init 命令必须保持容器存活以便 exec 执行命令envobject{}注入容器及每次 exec 的环境变量volumesobject{}宿主机到容器的 bind mount宿主机路径 - 容器路径mountsstring[][]透传的container run --mount原始规格networkstring—Apple container 网络挂载规格publishedPortsstring[][]端口发布规格--publishpublishedSocketsstring[][]套接字发布规格--publish-socketcpusnumber | string—分配的 CPU 数量memorystring—内存配额例如1Gplatformstring—OCI 平台例如linux/arm64archstring—多架构镜像时选择架构osstring—多平台镜像时选择操作系统rosettabooleanfalse是否启用容器内 RosettareadonlyRootfsbooleanfalse容器根文件系统只读挂载--read-onlysshbooleanfalse转发宿主机 SSH agent 套接字initbooleantrue启用 Apple 的 init 进程virtualizationbooleanfalse向容器暴露虚拟化能力capAddstring[][]追加的 Linux capabilitiescapDropstring[][]移除的 Linux capabilitiestmpfsstring[][]tmpfs 目标路径仅接受容器路径如/tmpdnsstring[][]DNS nameserver IPdnsSearchstring[][]DNS 搜索域noDnsbooleanfalse不在容器内配置 DNSlabelsobject{}容器标签Mastra 标签始终追加workingDirstring/workspace容器内工作目录已废弃推荐使用workingDirectorytimeoutnumber300000默认命令超时毫秒deleteOnDestroybooleantrue销毁时是否删除容器containerBinarystringcontainerApple container CLI 的可执行文件路径/名称不进 schemarunnerobject默认 runner自定义命令执行器主要用于测试不进 schema两个值得注意的细节workingDir与workingDirectory从 CHANGELOG.md 可知自 0.5.0 起mastra/core为所有沙箱 Provider 统一引入了workingDirectory选项workingDir降级为兼容别名。当两者同时设置时workingDirectory生效两者都未设置时才回落到 Provider 默认值/workspace。这一点在 单元测试 中有专门用例验证。tmpfs校验Apple container 的--tmpfs只接受容器内路径因此源码在构造时会调用validateTmpfsPaths校验Docker 风格的/tmp:rw,size64m规格会被直接拒绝并抛出错误。底层原理容器创建与命令执行生命周期start / stop / destroy沙箱继承自核心的MastraSandbox核心实现见 packages/core 的 workspace 模块并实现了三种状态迁移start()先container inspect检查同名容器是否存在——不存在用_buildRunArgs组装container run -d --name name --workdir dir参数包括全部 volumes、mounts、labels、端口、capability、资源限制等随后轮询inspect并反复执行container exec ... true直到容器可执行命令就绪超时 10 秒创建失败且deleteOnDestroy开启时会主动delete --force清理现场已存在且运行中直接复用不重启已存在但停止执行container start重启再等待就绪。stop()inspect确认存在且运行后执行container stop。destroy()默认执行container delete --force删除容器若deleteOnDestroy: false则只stop保留容器以便下次复用。命令执行exec shellexecuteCommand(command, args, options)的内部流程sandbox/index.ts先ensureRunning()确保容器在运行把命令与参数拼装为 shell 命令含参数引用shellQuote防止命令注入测试里有专门用例验证特殊字符被安全引用组装 CLI 参数container exec [--env KEY]... --workdir cwd container sh -lc shellCommand通过AppleContainerCliProcess继承自核心ProcessHandle以子进程方式运行container逐块解码 stdout/stderr支持流式回调与输出保留上限。单次命令执行支持以下选项ExecuteCommandOptionscwd本次命令的工作目录优先于实例级配置、env仅本次生效、timeout毫秒、abortSignal中止信号、onStdout/onStderr流式回调、maxRetainedBytes内存中保留的最新输出字节数超出部分以stdoutDroppedBytes等字段报告。超时与强制清理机制这是实现中最精巧的部分当设置了命令超时源码不会简单地在宿主机侧杀掉进程而是生成一段内层 shell 脚本——用timeout命令包裹命令并设置trap在超时时向子进程发送 TERM 后以退出码 124 退出同时把真实退出码写入临时文件避免命令自己退出 124与超时被杀混淆。判定超时的规则是退出码为 124 且 stderr 中含有特殊标记__MASTRA_APPLE_CONTAINER_TIMEOUT__否则即使退出码是 124 也不算超时这一正反用例均被单元测试和集成测试覆盖。此外CLI 子进程层面还有一重保护命令总超时 命令超时 10 秒宽限期超时后先SIGTERM1 秒内未退出再SIGKILL。AbortSignal也能随时终止命令。安全与所有权机制为了防止误操作他人容器源码实现了双重保护_assertMastraOwned与_assertCompatibleConfig所有权标签每次创建容器都会强制打上mastra.sandboxtrue、mastra.sandbox.idid、mastra.sandbox.config-hashhash三个标签。重连时若容器缺少与当前 sandbox id 匹配的 Mastra 标签会直接拒绝管理并抛出SandboxExecutionError配置哈希校验对镜像、命令、env、volumes、mounts、网络、资源等不可变配置做稳定序列化后取 SHA-256 前 16 位作为config-hash。重连时若哈希不一致说明容器是用另一套参数创建的同样拒绝接管。对应测试场景包括无标签容器的拒绝、配置不匹配的拒绝、以及新建容器未就绪即退出时自动清理。模板克隆一个沙箱配置派生一组沙箱clone()方法允许以某个已配置的沙箱为模板派生出一批独立的兄弟沙箱典型场景按项目各建一个沙箱。克隆会继承模板的全部配置镜像、资源、网络、安全项、标签仅支持按实例覆盖id与env且克隆过程不做任何 I/O——真正的容器创建在各自start()时才发生。需要说明的是idleTimeoutMinutes在此被忽略Apple container 没有 Provider 侧的空闲回收机制name也会被丢弃以便每个克隆独立命名。const template new AppleContainerSandbox({ image: ubuntu:24.04, workingDir: /workspace }); const projectSandbox template.clone({ id: mc-project-1, env: { GITHUB_TOKEN: token }, }); await projectSandbox.start();如何验证单元测试与集成测试该包在 src/sandbox 下提供了两层测试单元测试index.test.ts通过注入 MockAppleContainerCommandRunner精确断言container run参数构建顺序、生命周期调用、超时标记、环境变量合并、工作目录优先级、clone 行为等无需真实容器环境pnpm test:unit即可运行集成测试index.integration.test.ts需要真实的containerCLI。设置环境变量后运行MASTRA_APPLE_CONTAINER_INTEGRATION1 pnpm test:integration集成测试会真实地启动容器默认镜像alpine:3.20、执行命令、验证停止后重启同一容器重连已运行的容器超时命令确实被清理deleteOnDestroy 语义等端到端行为是最可靠的接入验证方式。适用场景与限制从源码结构看该 Provider 最适合在 macOS 本机为 Agent 提供低成本、免 Docker Desktop 的 Linux 隔离环境例如让 Agent 编译、运行、测试 Node 项目node:22-slim默认镜像或通过 bind mount 把宿主机仓库映射进容器做受控操作。使用中需注意仅适用于安装了 ApplecontainerCLI 的环境且容器为 LinuxOCI容器内命令不支持 stdin 写入sendStdin/closeStdin会抛出不支持错误tmpfs、env变量名等有严格校验环境变量名必须符合[A-Za-z_][A-Za-z0-9_]*工作目录等路径需使用绝对路径~与$HOME不会被展开版本演进请参考包的 CHANGELOG.md。更完整的 Mastra Workspace 概念与沙箱生态可继续阅读 workspaces 目录 下的其他 Provider 实现结合对比加深理解。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考