[DISCUSS] Clarify Maka sandbox contracts and runtime dependency access

[zhiiw]

This is a proposal for discussion, not an implementation decision. It is motivated by #5260 and the related #5266.

Related discussion: #4594 — Should Host-spawned stdio MCP servers run under SandboxPolicy?. This proposal focuses on session permission contracts and runtime dependency authorization; the specific MCP server isolation discussion can continue there.

English

1. The decision we should make explicit

Should Maka's local sandbox primarily restrict writes outside the workspace, or also restrict reads outside it? Both are useful contracts, but they have different compatibility and privacy costs.

My proposal is to preserve existing restricted-read sessions, unify how additional runtime access is authorized, and separately consider an explicitly selected development-compatible profile. Fixing Apple Git should not silently widen existing sessions. The immediate fix should be able to proceed without waiting for a complete sandbox redesign.

Evidence below was reviewed on 2026-09-14. Maka observations are pinned to ea990cab7ffa768dc1a574b539f73a83f8faabb8. This is a comparison of public contracts and selected source paths, not a security ranking or a common adversarial test run across products. Proposed guarantees are distinguished from observed implementation.

2. What #5260 exposes

Apple's /usr/bin/git uses the selected Xcode or Command Line Tools installation. In the reported case, the entry point runs, but Seatbelt blocks the dynamically loaded libxcrun.dylib in Xcode's developer directory. Once that is admitted, global Git configuration can present another read-access failure.

These are separate concerns: toolchain runtime access and user configuration access. A file being needed by a tool does not, by itself, authorize that tool to read it.

The reviewed #5266 revision, 3bfda10456162d45935b0bc893000451a98190f7, addresses selected toolchain libraries and exact Git configuration files. Its author reports that the real Seatbelt smoke could not complete in the local managed environment, and a physical full Xcode installation was not tested. This proposal does not replace that PR's implementation review.

3. What other runtimes actually promise

Here, Grok means the official Grok Build, and Pi means the former badlogic/pi-mono, now earendil-works/pi. The comparison is about execution modes, not model capabilities.

Runtime / mode	Filesystem contract	Enforcement scope and relevant limitation
Codex legacy workspace-write	Broad reads; writes limited to workspace, configured roots and temporary locations; network restricted by default	macOS Seatbelt. Restricted-read permission profiles are a separate option. Ordinary process compatibility rules also differ from filesystem-helper rules. [C]
Claude Code sandboxed Bash / Sandbox Runtime	Broad reads by default, bounded writes, configurable read denies and network rules	Bash and its descendants. Default sandboxing does not imply all credentials are unreadable. [A]
Grok Build workspace / strict	workspace reads broadly; strict narrows reads; sandbox is off by default	Applied to the agent process, with inherited filesystem restrictions. Published documentation explicitly says child-network blocking is not implemented on macOS. [G]
Gemini CLI with macOS Seatbelt enabled	Default permissive-open allows broad reads and network, confines writes; stricter and proxied profiles exist	Seatbelt or alternative execution environments such as Docker/Podman. “Default profile” does not mean sandboxing is enabled by default. [M]
Pi core / optional sandbox example	Core has no built-in sandbox; the example uses Sandbox Runtime with broad reads and selected sensitive-directory exclusions	The example mainly wraps Bash and includes a local-Bash path after initialization failure. It is not a complete mandatory-isolation template. [P]
OpenHands V1 documented Docker / Process / Remote providers	Docker provides a separate execution environment; Process runs locally without container isolation	An alternative to repeatedly admitting host dependencies. This is a version/deployment-specific provider contract. [O]

The main lesson is that a working Git command does not demonstrate compatibility under the same read boundary. Broad reads reduce dependency failures but expose more host data. Containers protect only resources that are not mounted or injected into them.

We should adopt useful mechanisms without importing weaker guarantees. For example, Grok's detailed documentation describes different startup-failure behavior, including some warning-and-continue paths; an irreversible applied policy does not mean every failure is fail-closed. Its overview and repository documentation also differ on some strict-profile write details, so this comparison does not rely on those details. [G]

4. Build on Maka's existing authority

Maka already has the right foundations:

• PermissionProfile describes filesystem and network access. The pinned workspace-write constructor grants workspace and temporary-directory writes, without a broad-read grant. [K1]
• ExecutionBoundary carries the actual profile and revision. Existing contracts cover expansion requests, decisions, conflicts, and closing pending requests after Host restart. Expansions conflicting with explicit denies are rejected. [K2]
• SandboxManager and platform backends select and prepare execution. The Bash path returns structured failures when a required sandbox is unavailable. [K3]
• The filesystem worker has a separate launch description, controlled environment and operation-specific dependency preparation. [K4]
• Runtime Host serves local or remote clients; paths and execution belong to the Host machine. [K5]

The gap is composition. User grants, platform defaults and runtime roots jointly determine actual access. In the pinned macOS implementation, ordinary access rules account for denied roots while runtime-root allowances are generated separately. We need tests of the complete composed policy, rather than assuming every allowance inherits the same deny semantics. Bash and filesystem-worker dependency sets may differ, but their authorization rules should not evolve independently. These are source observations and design concerns, not a demonstrated exploit claim. [K6]

Maka also has material platform differences: the pinned Bash path rejects managed arbitrary-shell execution on Windows and rejects PTY Bash when a sandbox is required. AppContainer support for the Windows filesystem worker is not equivalent to Windows shell support. [K3]

5. Proposed direction

A. Keep one permission system, with explicit execution contracts.

Contract	Proposed behavior
Existing restricted mode	Preserve workspace / authorized-resource reads plus declared platform dependencies. Keep existing session semantics.
Optional development-compatible profile	Explicitly authorize broader host reads, retain bounded writes and restricted network by default, and exclude identified protected resources. Clearly disclose that files outside the workspace may be readable.
External environment, later	Use a separately specified container, VM or remote execution boundary. Do not make this a prerequisite for the Apple Git fix.

My preference is to retain the current default initially and make compatibility opt-in. A future default for new sessions is a separate community decision. Neither an upgrade nor session resume should silently broaden an existing boundary.

Before introducing broad reads, identify and protect Maka's control resources: Host credentials, permission configuration, management endpoints, session databases and other sessions' private data. State which third-party credentials are protected; do not claim that all secrets are covered. A remote Host is not inherently an isolated environment, and a Linux container cannot replace a native Mac for Xcode builds.

B. Make additional access go through one preparation contract.

Client requests operation or permission change
  -> Runtime Host validates caller and ExecutionBoundary revision
  -> existing PermissionProfile + accepted platform capabilities
  -> discover resources needed by this execution target
  -> authorize and normalize resources, apply denies, check platform support
  -> immutable launch description
  -> platform enforcement, bounded IPC and process-tree lifecycle

Reuse the existing boundary and settlement owner; do not introduce a second sandbox-permission database. The launch description is derived evidence, not another authority.

Resolvers report candidate resources and their provenance, operations and scope. They cannot turn an arbitrary path into an approved grant. Host APIs and existing transaction/revision checks must enforce this, not just comments or TypeScript types. Preserve Maka's explicit-deny semantics rather than copying a different product's precedence rules.

Freeze the revision, environment, cwd, backend and grants before launch. Coordinate launch and permission narrowing through the Host lifecycle: revalidate pending launches, and drain or terminate existing processes where necessary. Expose the effective grants and unsupported capabilities in diagnostics without logging secret contents. A platform-rule change that expands access is a permission change.

Maka's persistent Host serves multiple sessions, so applying one session's irreversible sandbox to the entire Host would be inappropriate. Retain the trusted control process and restricted execution processes. Broker operations must remain bound to session authorization; a general unrestricted file or HTTP proxy would defeat the boundary.

Model traffic, Host-management traffic and command traffic must be distinguished. MCP, browser, plugin and other Host-side tools need explicit boundaries too; sandboxed Bash alone is not a claim that every agent action is isolated.

C. Fix Apple Git under that contract.

1. Exercise real CLT and full Xcode installations. Identify the necessary executables, libraries, resources and cache access, not only the first missing dylib.
2. Resolve and validate the selected toolchain on the Host. Environment variables locate candidates; they do not grant authority. Document supported relocated/symlinked installations and address replacement races.
3. Admit covered dependencies through the shared preparation path; use existing expansion requests for missing authorization. Do not grant all of /Applications, HOME or arbitrary PATH prefixes in restricted mode.
4. Treat Git configuration as separate read-only user-data access. Test includes, conditional includes and default/explicit ignores. Host-side discovery must not read unrestricted references first and only constrain the child later.
5. Do not hide failures by discarding global configuration, changing Git implementations or disabling the sandbox. Git authentication and credential helpers require separate capabilities.

One pre-launch scan cannot predict every future cd, git -C or branch-dependent configuration in arbitrary Bash. Report missing access or request it; do not expand silently while commands run. A file granted to Git in a shared shell sandbox is also readable by other programs in that sandbox. If publisher identity is part of toolchain validation, signature validity alone is insufficient, and one signed library does not validate a whole directory. [S]

6. Evidence, rollout and questions

Platform	Observed scope at the pinned revision	Required evidence for this work
macOS	Seatbelt command/worker paths; managed PTY unavailable; Apple Git fix still needs real-machine evidence	CLT and Xcode functionality; read/write/map boundaries; overlapping denies, aliases and replacement; claimed network/IPC limits
Linux	Existing backend and Bash path with path pinning, subject to Host capabilities	No shared-policy regression; unavailable backend refuses launch; cancellation/descendant isolation; document future-file coverage if globs are introduced
Windows	AppContainer filesystem-worker path; managed arbitrary shell unavailable	Preserve typed unavailability; worker regression tests; shell support remains a separate delivery

Acceptance should include both useful work and denied access: Git/config/ignore behavior; configuration readable but not writable; denied neighbors and Host resources inaccessible; native file tools, Bash and descendants respecting the same user-data boundary; no ambient secret/handle/socket bypass; and no unsandboxed retry.

For lifecycle changes, use real-process tests around approval settlement, launch handoff, Host death and concurrent permission narrowing before connecting new recovery behavior to Desktop/CLI. Process-crash evidence is not power-loss durability evidence.

Deliver this in separate PRs from current main: contract/capability documentation, shared additional-access enforcement, Apple toolchain support, Git configuration access, then an optional compatibility profile. External environments can have their own RFC. Each PR should prove one main invariant and state its owner, commit/launch boundary, failure state and rollback. Reverting a feature must not reopen a protected resource or reinterpret an existing session under wider permissions. Changes spanning three of schema, runtime protocol, Host lifecycle and platform I/O should start as Draft and be split. Green CI does not replace concurrency or isolation evidence.

Questions for maintainers and users:

1. Keep restricted reads as the initial default and add opt-in compatibility, or choose a different default for new sessions? What disclosure and migration contract would that require?
2. Which Maka control resources must always be protected from managed execution, and which third-party credential paths belong in the first supported set?
3. Do we agree that ExecutionBoundary and its existing settlement owner remain authoritative, with launch descriptions derived from them?
4. Can the first macOS: Agent Bash git fails with "unable to load libxcrun" under the Seatbelt sandbox #5260 milestone target real CLT + Xcode execution and negative access tests, leaving all-PATH discovery, arbitrary-tool compatibility and Windows shell support to separate work?

References

• [C] Codex: Legacy policy definition, Seatbelt implementation, permission profiles.
• [A] Claude Code: Sandboxed Bash documentation, Sandbox Runtime.
• [G] Grok Build: Official overview, detailed contract at reviewed commit, implementation.
• [M] Gemini CLI: Sandbox configuration and backends.
• [P] Pi: Security model, optional sandbox example.
• [O] OpenHands: V1 sandbox providers.
• [K1] Maka: PermissionProfile.
• [K2] Maka: ExecutionBoundary and expansion contracts.
• [K3] Maka: SandboxManager, Bash preparation.
• [K4] Maka: Filesystem-worker launch preparation.
• [K5] Maka: Runtime Host.
• [K6] Maka: Seatbelt backend, Windows sandbox RFC.
• [S] Apple: Code-signing requirements.

Prepared with Codex assistance: public-source research, drafting and translation.

---

中文版（点击展开）

相关讨论：#4594 — Host 启动的 stdio MCP server 是否应受 SandboxPolicy 约束？。本文聚焦会话权限契约和运行依赖授权；MCP server 隔离的具体方案可以继续在该讨论中推进。

1. 希望先明确的决定

Maka 的本地 sandbox 主要限制工作区外写入，还是同时限制工作区外读取？两种契约都有价值，但兼容性和隐私成本不同。

我的建议是：保留现有受限读取会话，统一附加运行权限的授权，再单独讨论显式选择的开发兼容 profile。 不能借修复 Apple Git 静默扩大旧会话权限；近期修复也不必等待全面重构。

调研日期为 2026-09-14，Maka 源码固定在 ea990cab7ffa768dc1a574b539f73a83f8faabb8。本文比较公开契约和部分源码，不是安全排名，也没有对所有产品运行同一组攻击／兼容性测试。以下建议不代表已有保证。

2. #5260 暴露了什么

Apple /usr/bin/git 使用选中的 Xcode／Command Line Tools。报告中 Git 入口能够执行，但 Seatbelt 拦截了 Xcode 路径中的 libxcrun.dylib。补上动态库读取后，用户全局 Git 配置又可能读不到。

这是两个问题：工具链运行依赖和用户配置读取权限。工具需要某个文件，并不自动产生读取授权。

已审阅的 #5266 版本 3bfda10456162d45935b0bc893000451a98190f7 处理了选中工具链目录和精确 Git 配置文件。作者说明真实 Seatbelt smoke 因环境限制未完成，完整 Xcode.app 尚无实机验证。这份提案不替代该 PR 的实现审查。

3. 其他 runtime 的契约并不相同

Grok 指官方 Grok Build；Pi 指原 badlogic/pi-mono、现 earendil-works/pi。比较的是执行模式，不是模型能力。

项目／模式	文件权限契约	隔离落点与限制
Codex 传统 workspace-write	广泛读取，写入限工作区、指定目录及临时目录；默认限制网络	macOS Seatbelt；另有受限读取 profile；普通进程与 filesystem helper 的兼容规则不同。[C]
Claude Code sandboxed Bash／Sandbox Runtime	默认广泛读取，限定写入，可配置读取禁止及网络规则	Bash 及子进程；默认不代表所有凭据都不可读。[A]
Grok Build workspace／strict	workspace 广泛读取，strict 收窄读取；sandbox 默认关闭	整个 agent 进程受限，子进程继承文件限制；文档明确 macOS 子进程断网未实现。[G]
Gemini CLI 启用 macOS Seatbelt	默认 permissive-open 广泛读取、限制写入、允许网络；有严格及代理 profile	Seatbelt 或 Docker／Podman 等环境；默认 profile 不代表默认开启沙箱。[M]
Pi 核心／可选沙箱示例	核心无内置 sandbox；示例广泛读取并排除部分敏感目录	示例主要包装 Bash，初始化失败后有普通 Bash 路径，不能直接作为强制隔离模板。[P]
OpenHands V1 文档中的 Docker／Process／Remote	Docker 提供独立执行环境；Process 是无容器隔离的本机进程	可通过预配置环境处理复杂依赖；属于特定版本／部署的契约。[O]

Git 能运行，不等于在同样严格的读取边界下也能运行。广泛读取能减少依赖问题，也暴露更多宿主数据；容器只能保护未挂载、未注入的资源。

应借鉴机制而非照搬保证。例如 Grok 详细文档区分启动失败处置，包含部分警告后继续的路径；“策略应用后不可逆”不等于“任何失败都 fail closed”。其概要与仓库对 strict 的部分写入范围表述也不同，本文不依据这些细节作更强保证。[G]

4. 复用 Maka 已有的权限事实源

已有基础包括：

• PermissionProfile 描述文件与网络权限；当前 workspace-write 显式授予工作区和临时目录写入，没有广泛读取授权。[K1]
• ExecutionBoundary 携带实际 profile 和 revision；已有扩权、批准／拒绝／冲突、Host 重启关闭未决申请等契约。与显式 deny 冲突的扩权被拒绝。[K2]
• SandboxManager 与平台后端准备执行；Bash 在强制沙箱能力不可用时返回结构化失败。[K3]
• filesystem worker 有独立启动描述、受控环境、按操作准备依赖的路径。[K4]
• Runtime Host 服务本地／远程客户端，路径解析和执行发生在 Host 机器上。[K5]

缺口在权限合成：用户授权、平台默认和 runtime roots 共同决定实际访问，但应能在一个结果里核对它们的来源和效果。该提交的 macOS 普通授权分支处理 deny，runtime roots 却单独生成 allow；必须验证完整策略，不能假设所有分支自然继承相同限制。Bash 与 worker 所需依赖可以不同，授权规则不应分别演化。这是源码观察与设计关注点，不是已完成利用验证的漏洞结论。[K6]

平台能力也不对称：该提交拒绝 Windows managed 任意 shell，并拒绝强制沙箱下的 PTY Bash。Windows filesystem worker 支持 AppContainer，不等于 Windows shell 已支持。[K3]

5. 建议方案

A. 一个权限体系，明确不同执行契约。

契约	建议行为
现有受限模式	保留工作区／已授权资源读取，加上声明的基础运行依赖；不改变旧会话语义
可选开发兼容 profile	显式授权较广宿主读取，仍限制写入、默认限制网络，排除明确保护资源；说明工作区外文件可能可读
后续外部执行环境	单独定义容器、VM 或远程执行边界；不作为 Apple Git 修复的前置条件

倾向先保留当前默认，兼容模式作为 opt-in。未来新会话的默认由社区另行决定，升级和恢复不能静默扩大既有边界。

引入广泛读取前，应明确保护 Maka 控制资源：Host 凭据、权限配置、管理端点、会话数据库和其他会话私有数据。第三方凭据要列出保护范围，不能声称覆盖所有秘密。远程 Host 本身不是隔离证明；Linux 容器不能替代需要 Xcode 的原生 Mac 构建。

B. 附加权限进入统一启动准备契约。

客户端请求操作／权限变化
  → Runtime Host 校验调用者与 ExecutionBoundary revision
  → 现有 PermissionProfile + 已接受的基础能力
  → 发现本执行对象需要的资源
  → 授权、规范化、应用 deny、检查平台能力
  → 不可变的本次启动描述
  → 平台执行、受限 IPC、进程树生命周期管理

复用现有 boundary 和结算 owner，不另建 sandbox 权限数据库。启动描述是派生证据，不是第二事实源。

解析器只报告候选资源、来源、操作及范围，不能将任意路径变成已批准授权。Host API 和现有事务／revision 约束负责落实，不能仅靠注释或类型。保留 Maka 显式 deny 的语义，不因复制其他产品的规则优先级而改变契约。

启动前固定 revision、环境、cwd、后端和授权。Host 生命周期同时协调启动与权限收紧：待启动请求重新校验，已有进程必要时排空或终止。诊断展示实际授权及未支持能力，不输出秘密内容；平台规则升级若扩权，也按权限变更处理。

Maka 的持久 Host 服务多个会话，不适合直接施加某一个会话的不可逆进程沙箱。保留可信控制进程与受限执行进程的分离；broker 操作绑定会话授权，不能提供通用越权文件或 HTTP 代理。

模型网络、Host 管理网络和命令网络分别授权。MCP、浏览器、插件等宿主工具也需要明确边界，不能仅凭 Bash 已隔离就承诺所有 agent 操作已隔离。

C. 在这个契约下修复 Apple Git。

1. 用真实 CLT 和完整 Xcode 验证启动链，识别程序、库、资源及缓存访问，不只解决第一个 dylib 报错。
2. 在 Host 上验证实际工具链。环境变量只定位候选，不产生授权；说明搬迁／符号链接支持范围并处理路径替换风险。
3. 已覆盖依赖进入共享准备路径，缺少授权走现有扩权申请。受限模式不开放整个 /Applications、HOME 或任意 PATH 前缀。
4. Git 配置作为独立只读用户数据授权，测试 include、条件 include、默认及显式 ignore；宿主不能先无约束读取引用，再只约束子进程。
5. 不通过丢弃全局配置、更换 Git 实现或关闭沙箱隐藏失败；认证和 credential helper 是独立能力。

一次预扫描不能预测任意 Bash 中后续的 cd、git -C 和分支变化。缺少访问时明确失败或申请，不在运行中自动开放。同一 shell 沙箱里授权给 Git 的文件，也能被其他程序读取。若要求确认 Apple 发布者，需验证签名身份；单个库签名也不能证明整个目录边界。[S]

6. 验收、交付与讨论问题

平台	固定提交的现状	本次工作需要的证据
macOS	Seatbelt 命令／worker；managed PTY 不可用；Apple Git 仍需实机补证	CLT、Xcode 功能；读／写／映射边界；deny 重叠、别名和替换；所声明网络／IPC 限制
Linux	已有后端、Bash、路径 pinning，受 Host 能力限制	共享策略不退化；不可用拒绝启动；取消和后代隔离；如引入 glob，说明未来文件覆盖
Windows	AppContainer worker；managed 任意 shell 不可用	保留 typed unavailable；worker 回归；shell 单独交付

验收同时包含正常工作与拒绝访问：Git／配置／ignore 正常；配置可读不可写；邻近禁止文件和 Host 资源不可访问；原生文件工具、Bash 及后代遵守同一用户数据边界；环境秘密、继承句柄、socket 不成为旁路；没有无沙箱重试。

涉及生命周期的改动，先做批准结算、启动交接、Host 强杀和并发权限收紧的真实进程测试，再接新的 Desktop／CLI 恢复行为。进程崩溃证据不等于断电耐久性证据。

从最新 main 分别交付：契约／能力文档、统一附加授权、Apple 工具链、Git 配置、可选兼容 profile。外部环境另开 RFC。每个 PR 证明一个主要不变量，写出 owner、提交／启动边界、失败状态和回滚方式。回滚不能重开受保护资源，也不能以更宽权限重新解释已有会话。跨 schema、runtime protocol、Host lifecycle、platform I/O 三个边界的改动默认 Draft 并拆分；CI 全绿不替代并发和隔离证据。

希望社区先讨论：

1. 是否保留受限读取默认、增加 opt-in 兼容模式？若调整新会话默认，应如何说明隐私代价和迁移规则？
2. 哪些 Maka 控制资源必须保护，哪些第三方凭据进入首批明确保护范围？
3. 是否认同 ExecutionBoundary 和现有结算 owner 保持唯一授权事实源，启动描述由它派生？
4. macOS: Agent Bash git fails with "unable to load libxcrun" under the Seatbelt sandbox #5260 首期能否以真实 CLT＋Xcode 和访问反例为门槛，将全 PATH 发现、任意工具兼容和 Windows shell 留给独立交付？

参考资料见上方 References，各编号与中文正文对应。

使用 Codex 辅助完成公开资料调研、起草和翻译。

[keliwang]

I tend to default to opening up global read access to avoid constantly patching the current read-only path rules, which is endless. For users with strong privacy needs, consider providing a mode that enforces restrictions to the current workspace, which can be patch-free and used only for limited scenarios.

中文版

我倾向于默认放开全局读，避免不断在现在的只读路径规则里打补丁，这是没有尽头的。对于有强隐私需求的使用者，可以考虑提供一个强制限制到当前 workspace 的模式，这个模式可以完全不打补丁，仅用于有限的场景。