Skip to content

feat(core): sandbox agent shell commands with MXC - #64093

Draft
benjaminfrombe wants to merge 2 commits into
anomalyco:devfrom
benjaminfrombe:sandbox-mxc
Draft

benjaminfrombe wants to merge 2 commits into
anomalyco:devfrom
benjaminfrombe:sandbox-mxc

Conversation

@benjaminfrombe

@benjaminfrombe benjaminfrombe commented Nov 15, 2026 •

Copy link
Copy Markdown

Issue for this PR

Addresses the sandboxed-execution part of #48411. Supersedes #63599 (see below).

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

Opt-in OS-level sandbox for the shell tool, enforced by Microsoft MXC (@microsoft/mxc-sdk): Seatbelt on macOS, bubblewrap on Linux, ProcessContainer on Windows. Off by default; sandbox.enabled: true in user config turns it on.

Design decisions, and how this differs from #63599:

  • One backend instead of hand-rolled profiles. feat(core): add opt-in OS-level shell sandbox #63599 hand-writes a bwrap argv and a Seatbelt profile, has no Windows backend, and its macOS profile is only string-tested. MXC gives us maintained profiles for all three platforms, and this PR's live tests execute the macOS backend for real.
  • Repository config cannot touch the sandbox. Sandbox settings are honored only from user-level config (global, system, MDM, explicit). A document inside the workspace, or in a directory the workspace was discovered from by walking up, is ignored for sandbox policy. This closes the "repo config can loosen the user's sandbox" review point on feat(core): add opt-in OS-level shell sandbox #63599.
  • The restart escape is closed, as far as each backend allows. In workspace-write mode, opencode.json, opencode.jsonc, .opencode, .claude and .agents cannot be written or planted by a sandboxed command. On macOS that includes paths that do not exist yet (verified: a fresh-workspace planting attempt is denied). On Linux, paths that exist are enforced as read-only carve-outs, but bwrap cannot bind a missing read-only source and the backend's deny fallback creates the missing path as a stray host directory (reported upstream: Linux bubblewrap: deniedPaths for a nonexistent path creates a stray directory on the host that persists after exit microsoft/mxc#1780), so not-yet-existing paths are left unprotected there in v1, as a documented gap. On Windows, where the backend does not enforce read-only carve-outs under a writable root at all, protected paths are denied outright instead. This addresses the blocking review finding on feat(core): add opt-in OS-level shell sandbox #63599.
  • Strictest defaults. Enabled-but-unset resolves to read-only with network denied; an invalid sandbox block normalizes to the strictest policy instead of being dropped (kept from feat(core): add opt-in OS-level shell sandbox #63599).
  • Separate escape permission. The shell tool gains a sandbox input; sandbox: false asserts shell_unsandboxed (shipped as ask, after the * allow) before the ordinary shell approval, so approving a sandboxed command never approves running it unsandboxed. Deny/allow rules on shell_unsandboxed act as the escalation policy, the equivalent of Codex's escalation modes.
  • Fail-closed everywhere. Remote workspace, unsupported platform, missing backend (bwrap on Linux), missing SDK package, or a network-deny policy the Windows backend cannot enforce yet: the command is not run, with a message saying why. Never a silent unconfined fallback.
  • Scope. Enforcement lives in the shell tool, not Shell.Service, so user ! commands and plugin shells are not confined (a review point on feat(core): add opt-in OS-level shell sandbox #63599). Policy is pinned per Location in an Effect service, not a module-level Map. readable_roots is dropped: the backend allows reads outside writable roots by default, so it would be dead config.

Known limitations, stated up front:

  • Sandboxed commands run to completion in the foreground with captured output: no background mode, no interactive terminal, no mid-run stop. MXC's stdio streams do not deliver under bun 1.4.x (verified; they work under node), so streaming is a follow-up.
  • Windows: ProcessContainer enforces filesystem containment (verified on Windows 11 build 26300), but a network-deny policy is accepted while direct egress still works, so network: "deny" fails closed there with an explanation until MXC can enforce it. Filesystem-only sandboxing on Windows is available by setting network: "allow" explicitly.
  • Intel macOS fails closed: the MXC 1.1.0 npm tarball ships no x64 macOS dylib yet.
  • Install size: the SDK adds ~39 MB compressed / 118 MB unpacked. koffi is added to trustedDependencies (its postinstall fetches prebuilds; bun blocks it by default).
  • MXC release builds on Windows emit required Microsoft diagnostic telemetry; this is disclosed in the docs.

No feature flag: the sandbox config block defaults to off, which is the gate; the PR is a draft pending the design review CONTRIBUTING.md asks for, and #63599 may be closed in favor of it if the approach is approved.

How did you verify your code works?

  • cd packages/core && bun run typecheck:tsc clean (bun check needs bun 1.4.4; my local bun is 1.4.2, so I used the tsc variant CI treats as source of truth).
  • bun run script/test.ts test/sandbox.test.ts: 21 pass, 2 skip (Windows-only cases), 0 fail. The live tests, gated on MXC backend availability, run the real macOS Seatbelt backend: write inside allowed, write outside denied, config and plugin planting denied (existing and not-yet-existing paths), network egress denied, read-only mode enforced, timeout kills the command.
  • test/tool-shell.test.ts: 101 pass, 0 fail, including 4 new tests (routes through the sandbox, timeout notice, shell_unsandboxed asserted before shell, no escape prompt when the sandbox is off).
  • test/agent.test.ts, test/config/normalization.test.ts, test/subagent-idle-e2e.test.ts: 68 pass, 0 fail. packages/schema: 93 pass, 0 fail.
  • Windows 11 (Parallels VM, build 26300, node 24): ProcessContainer available; verified with the exact request shape this PR builds: workspace writes allowed, write outside denied, opencode.json and .opencode/plugins planting denied, deniedPaths enforced, and the network-deny gap that motivates the fail-closed Windows behavior.
  • Linux (Debian 13 VPS, bwrap 0.12.0, node 24): bubblewrap backend verified with the exact request shape this PR builds: output and exit-code capture, workspace writes allowed, write outside denied, existing opencode.json read-only (write denied, read allowed), read-only mode enforced, network egress denied (curl exit 6), timeout kill with timedOut: true. Also surfaced the two upstream behaviors (missing readonly source fails the launch; missing denied path creates a stray host directory) that shape the documented Linux gap, Linux bubblewrap: deniedPaths for a nonexistent path creates a stray directory on the host that persists after exit microsoft/mxc#1780.
  • Full core suite: 7522 tests, 1 failure (tool-output emoji split), which also fails on pristine dev (verified with git stash), so zero new failures from this branch.

Screenshots / recordings

Not a UI change.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

Opt-in OS-level sandbox for the shell tool, enforced by Microsoft MXC
(Seatbelt on macOS, bubblewrap on Linux, ProcessContainer on Windows).

- sandbox config block, default off; an invalid block resolves to the
  strictest policy instead of being dropped
- settings are honored from user-level config only: a repository cannot
  enable, loosen or tighten the sandbox or add writable roots
- read-only and workspace-write modes, network deny by default
- protected config paths (opencode.json, .opencode, .claude, .agents)
  cannot be written or planted by a sandboxed command, closing the
  restart escape; denied outright on Windows where read-only carve-outs
  are not enforced
- fail-closed everywhere: unsupported platform, missing backend, remote
  workspace, or a network-deny policy Windows cannot enforce yet means
  the command does not run, never a silent unconfined fallback
- separate shell_unsandboxed permission, asserted before the shell
  approval, so approving a sandboxed command never approves escaping it
- live enforcement tests gated on backend availability: macOS Seatbelt
  and Windows ProcessContainer verified end to end

Addresses the sandboxed-execution part of anomalyco#48411. Supersedes anomalyco#63599.
bwrap cannot bind a read-only source that does not exist, which fails the
whole launch, and the backend's deniedPaths fallback creates the missing
path as a stray directory on the host (microsoft/mxc#1780). Linux now
carves out protected paths that exist and leaves the rest alone in v1,
documented as a known gap; macOS and Windows behavior is unchanged.

Verified on Debian 13 with bwrap 0.12: read-only carve-outs for existing
paths are enforced (write denied, read allowed), network egress denied,
read-only mode enforced, timeout kill works.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant