phoebus_os/docs/adr/0006-package-lanes.md
Phoebus 25f7381b4a
Some checks are pending
ci / test (push) Waiting to run
feat(desktop): add Mango + DankMaterialShell profile with rollback, assistant and release foundations
- Mango + DankMaterialShell desktop option (desktop.profile = "mango") through
  the GURU overlay with scoped ~amd64 keywords, a sealed session entry point and
  a dwl fallback session (ADR 0009).
- Coherent rollback/recovery: coordinated @ + @var snapshots, fstab and BLS
  root-subvolume rewriting, matching-kernel selection, snapshot recovery entry,
  retention/space gates and sys undo (ADR 0007).
- Installed assistant (sys ask) with an OS-level systemd sandbox boundary and
  fail-closed typed plans; resolved package effects bound to approval.
- Nix build isolation enforced (sandbox, no fallback) plus lifecycle/cleanup.
- Desktop helpers (menu/lock/idle), transaction log, release gates with atomic
  publish and signing helpers, and a Debian-Live appliance VM harness.
2026-09-21 03:46:52 -07:00

7.8 KiB

ADR 0006: Package lanes — Portage, Flatpak, and Nix (built in)

  • Status: Accepted
  • Date: 2026-09-20

Context

Phoebus is built on Gentoo/Portage and must stay a thin layer over it. There is a real need for binary options for non-core software (developer tooling, alternate versions, packages awkward or slow to compile) without (a) maintaining a private Gentoo binhost, or (b) letting a second package manager claim ownership of the system.

The decision here is that Nix is part of the distro by default — the same way the AI assistant is: always present and ready, but never authoritative and never required. A Phoebus system must remain completely usable with Portage alone; a user who ignores Nix must not notice it.

Options considered: a second distro via Distrobox/pacman, Nix, Homebrew, native -bin ebuilds, a third-party Gentoo binhost, and Flatpak.

Relevant facts established:

  • The official Gentoo binhost is a single non-systemd (hardened) baseline, so systemd/desktop packages mostly compile from source. We will not maintain a private binhost.
  • nix is not in the Gentoo main tree, so Phoebus ships and manages it itself.
  • Nix is strong for reproducible, multi-version developer environments and poor for GPU/Wayland desktop apps on a non-NixOS host (nixGL, Electron sandbox).
  • Flatpak is already designed into Phoebus and is the right fit for sandboxed GUI apps.

Decision

Adopt three package lanes, all present on a default install, with strict ownership:

Lane Owns Availability
Portage (authoritative) kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot stack, system services, compilers/toolchain always
Flatpak graphical desktop apps (Chromium, Firefox, Spotify, Electron), sandboxed always
Nix developer tools, alternate versions, reproducible per-project environments, packages inconvenient in Portage always, user-level use

Portage's native -bin ebuilds (google-chrome, steam-launcher, discord-bin, ...) remain the vendor-blob lane; no new tool is introduced for them.

Nix is baked in, but "baked in" describes availability, not authority:

  • the Nix toolchain and daemon are shipped and configured by the installer;
  • Portage still installs and updates Nix itself, so the daemon is system-managed rather than a stray curl | sh artifact;
  • no core component, service, library or application depends on Nix being used;
  • ignoring Nix has no effect on the system.

How Nix is baked in without surrendering ownership

A normal binary ebuild is not possible: the upstream Nix installer hardcodes /nix, calls sudo, and runs nix-store --load-db against the real root, with no DESTDIR/--root support. Repackaging it into a target image would require re-implementing that bootstrap; building Nix from source is a separate, large option.

  1. Bootstrap the pinned, verified official release with discrete commands in the target chroot (no curl | sh, no sh -c), reproducing the installer's steps: copy the store, nix-store --load-db, create the nixbld group and users, wire the profile, and install/enable the nix-daemon units.
  2. Multi-user, systemd-managed. nix-daemon.service/.socket are installed and enabled; the store lives at /nix.
  3. Pinned and verified. The Nix version and tarball SHA-256 are embedded and checked fail-closed; nixpkgs is pinned per environment (flake lock / channel revision), never "latest".
  4. No NixOS model. No configuration.nix, no system profiles, no Nix-managed services. Nix manages user environments only.
  5. On by default, VM-verified. A disposable-VM install confirmed the bootstrap (nix-daemon active, nix shell nixpkgs#hello works), so packages.nix is on by default; NIX_ENABLED='no' opts out. Nix is never a hard dependency of boot, run or recovery.

Rules

  1. Portage is the only authority over the running system. Nix and Flatpak never provide kernel, drivers, Mesa, PipeWire, systemd, core libraries or boot.
  2. Nix is user-level in effect. It provides developer tools and project environments, never system components.
  3. Never required. The system is fully functional with Portage alone; the base image and all services work if Nix is unused or removed.
  4. GUI apps go to Flatpak, not Nix.
  5. No arbitrary remote evaluation by default. Nix commands run by the assistant are bounded (no arbitrary flakes or URLs), so eval-time fetching is not an AI-reachable supply-chain surface.

AI integration

The differentiated use is a typed, assistant-driven action:

CreateDevEnvironment { name, packages[], versions[] }
  • executed unprivileged through Exec (no shell, no root for the user action);
  • inputs validated against a bounded set;
  • never mutates the base system;
  • the deterministic broker reports which lane satisfied a request.

A future sys chooser must prefer deterministically: system/compiler/Mesa/ drivers → Portage only; GUI → Flatpak; per-project/dev → Nix.

Explicit non-goals

  • A universal pkg install meta-manager that silently picks a source (deferred; provenance and support burden).
  • NixOS-style system configuration.
  • A second full distro (Distrobox, pacman) — rejected: a second rootfs to maintain with weaker isolation than Flatpak.
  • A third-party Gentoo binhost — rejected: trust, signature and availability.
  • Homebrew — rejected: not packaged for Gentoo, FHS prefix shadowing, and it adds nothing over Nix for the developer lane.

Consequences and risks

  • Every install now carries the Nix toolchain, a root daemon, and a growing /nix store; image and disk usage increase.
  • There are now two trust/update pipelines (gentoo + nixpkgs) on every system, each with its own CVEs and update cadence. The daemon being Portage-managed keeps ownership clear, but the risk is real and must be documented to users.
  • GUI/GPU stays Flatpak's job, consistent with this session's finding that Nix is a poor fit there.
  • The nix-daemon runs as root; it is a privileged component and must be treated as one (service hardening, update tracking).

Next steps

  1. Finish Flatpak integration: a documented app-install path and desktop integration. The xdg-desktop-portal (+ -gtk/-wlr backends) are installed, bounded flatpak_install/flatpak_remove/flatpak_list typed actions exist, and flathub is configured; an actual app install and the file chooser/screencast portals still need VM verification.
  2. Author the Phoebus overlay sys-apps/nix ebuild (a bootstrap-style ebuild; see ADR 0008) so emerge owns installation, upgrades and removal. Until it ships, the installer provisions the same lifecycle directly.
  3. CreateDevEnvironment/nix_prepare bounded typed actions: nix_prepare is implemented; a richer per-project environment action remains.
  4. Consider a thin sys-level source chooser (not a general pkg).

Binary strategy (reconciled)

The roadmap once proposed publishing a private signed binhost to stop the desktop set compiling. That conflicts with the rejection of a private/third-party binhost above and would add infrastructure and trust obligations silently.

The sustainable strategy is:

  • Portage source or the official signed Gentoo binhost, whichever matches the package's USE. Signature verification stays on (ADR 0004); no private binhost is maintained.
  • Flatpak for sandboxed GUI applications that the official binhost cannot serve (Chromium, Spotify, Electron).
  • Nix for developer tools, alternate versions and reproducible per-project environments (ADR 0008).

Packages the official OpenRC/hardened binhost cannot satisfy (systemd, polkit, NetworkManager, a desktop USE set) compile from source. That cost is accepted and measured (docs/STATUS.md records the compile times), not hidden behind a new binhost.