Skip to content

sandbox.md

Latest commit

 

History

History
82 lines (49 loc) · 3.34 KB

sandbox.md

File metadata and controls

82 lines (49 loc) · 3.34 KB
Raw

Sandbox Backends

Linux bubblewrap backend

Fusion supports an opt-in Linux sandbox backend using bubblewrap (bwrap).

  • Enable with sandbox.backend = "bubblewrap"
  • Default remains native
  • If unavailable, behavior follows failureMode (fail-hard or fallback-native)

Install

  • Debian/Ubuntu: sudo apt install bubblewrap
  • Fedora: sudo dnf install bubblewrap

Policy mapping

policyToBwrapArgs() translates sandbox policy into bwrap args:

  • Writable binds (--bind): worktree path, pnpm store path, plus configured allowedWritePaths
  • Read-only binds (--ro-bind): repo root (when distinct), system runtime paths (/usr, /bin, /lib, /lib64), TLS/DNS paths, and node binary directory
  • Temporary filesystem: --tmpfs /tmp
  • Working directory: --chdir <worktreePath>
  • Network isolation: allowNetwork=false adds --unshare-net
  • Environment isolation: --clearenv plus allowlisted passthrough (PATH, HOME, USER, LANG, LC_*, NODE_*, npm_*, PNPM_*, CI, FUSION_*)

Port 4040 guard

Port 4040 is reserved for the production dashboard. Sandbox policy rejects allowedPorts containing 4040 unless allowPort4040Override=true is explicitly set.

Fusion workflow defaults

Use fusionWorktreePreset(ctx) to get the standard Fusion-friendly defaults:

  • Worktree writable
  • pnpm store writable
  • .fusion/fusion.db is not added to writable mounts

Troubleshooting

If you see bwrap: setting up uid map: Permission denied, unprivileged user namespaces may be disabled by host policy/kernel settings. Enable user namespaces or use sandbox.backend = "native" as a fallback.

Related settings

See docs/settings-reference.md for full sandbox settings schema and precedence.

macOS sandbox-exec backend

Fusion supports an opt-in macOS sandbox backend using Apple's sandbox-exec (Seatbelt).

  • Enable with sandbox.backend = "sandbox-exec"
  • Default remains native
  • If unavailable, behavior follows failureMode (fail-hard or fallback-native)

Install / availability

/usr/bin/sandbox-exec ships with macOS. If detection fails, install Xcode Command Line Tools and retry.

Policy mapping

policyToSbplProfile() translates policy into an SBPL profile:

  • Base deny policy with additive allows
  • Writable paths: worktree, pnpm store, /private/tmp, and user temp (/private/var/folders/.../T/)
  • Read paths: repo root (when needed), Node binary directory, and curated system/runtime paths (/usr, /bin, /sbin, /System, /Library, resolver/cert/hosts/services/timezone paths)
  • Network: allowNetwork=true enables outbound and local bind, allowNetwork=false denies network

Port 4040 guard

Port 4040 is always blocked in the emitted SBPL profile ((deny network-bind (local ip "*:4040"))), and policy rejects explicit 4040 allowance unless allowPort4040Override=true is set.

.fusion/ write guard

Writable paths under .fusion/ (including .fusion/fusion.db and .fusion/tasks/**) are rejected by policy validation.

Troubleshooting

If commands fail with sandbox-exec: ...: Operation not permitted, expand allowedReadPaths/allowedWritePaths for required inputs/outputs.

Deprecation note

Apple marks sandbox-exec as deprecated. It remains functional for many workflows, but failureMode = "fallback-native" is the recommended hedge when host support varies.