46 lines
1.7 KiB
Markdown
46 lines
1.7 KiB
Markdown
# 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.
|