83 lines
3.3 KiB
Markdown
83 lines
3.3 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.
|
|
|
|
## 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.
|