root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
2c3a777bcaefe5ca0e12e30bff3296b3bcaf3136
fusion/docs/sandbox.md
gsxdsm a242f1b449 fix(FN-7952): migrate bundled plugins to PostgreSQL (#2111) 
## Summary

Bundled plugins now persist shared runtime state in project-scoped
PostgreSQL tables instead of maintaining independent SQLite authority.
Reports, CLI Printing Press, Compound Engineering, Roadmap, Even
Realities, and WhatsApp all follow the same ownership and startup
contract as Fusion core.

## Design decisions

- Plugin schema hooks run through the host’s PostgreSQL owner and
enforce project isolation.
- The SDK exposes the host contract needed by bundled plugins without
importing engine internals.
- Legacy Roadmap ownership fixtures use the supported empty-owner
sentinel, preserving current composite primary/foreign keys while
exercising backfill behavior.
- The lockfile travels with the Even Realities PostgreSQL dependency so
packaged installs remain reproducible.

## Validation

- All six affected plugin builds pass.
- Affected plugin suites pass: 773 tests across Printing Press, Compound
Engineering, Even Realities, Reports, Roadmap, and WhatsApp.
- `pnpm test:gate` passes all 478 gate tests.
- This PR changes 40 files.

## Stack

- Depends on #2110 → #2109 → #2108.
- The documentation/release PR completes the stack.

Related: #2105


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Breaking Changes**
* PostgreSQL is now required for runtime storage; SQLite files are used
only as one-time migration inputs.
  * The legacy `FUSION_NO_EMBEDDED_PG` fallback has been removed.

* **New Features**
* Added project-isolated PostgreSQL storage for plugins, reports, tasks,
notifications, and other plugin data.
  * Added agent tools for reports and CLI service drafts.
  * Added PostgreSQL schema initialization support for plugin authors.

* **Bug Fixes**
  * Improved migration and recovery of legacy plugin state.
* Prevented cross-project data access and strengthened transactional
schema updates.

* **Documentation**
* Updated storage, migration, deployment, plugin authoring, CLI, and
dashboard guidance for PostgreSQL.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-07-15 00:27:59 -07:00

3.4 KiB
Raw Blame History

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/ compatibility metadata and task artifacts are 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/project.json, retained migration inputs, 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.

Reference in New Issue View Git Blame Copy Permalink