fusion/docs/sandbox.md

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.