AI and Nix are now always-present parts of Phoebus (not optional add-ons): the assistant ships with a local model so it works offline and in recovery, and Nix is a second package lane shipped and updated through Portage. Installation needs the network; the installed system must boot, run and recover without it. The assistant is the preferred front-end, never a gate: the deterministic CLI (sys, emerge, nix, flatpak) is always available. The model still never holds privilege. Records ADR 0006 (package lanes).
6.3 KiB
ADR 0006: Package lanes — Portage, Flatpak, and Nix (built in)
- Status: Proposed
- 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.
nixis 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 | shartifact; - 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
- Ship it as a Portage package, not the upstream installer. Provide a
Phoebus overlay ebuild for Nix (e.g.
sys-apps/nix) that installs the toolchain, creates the store andnixbldbuild users, and installs anix-daemon.serviceunit. The installer adds the overlay and emerges it as part of the base/desktop package set. - Multi-user, system-managed. Because it is a real package, a root
nix-daemonis acceptable: it is enabled like any other service, updated throughemerge, and audited with the rest of the system. - Pinned and verified. The ebuild pins the Nix version and verifies the
upstream release tarball by SHA-256. The upstream
curl | shinstaller is never used. nixpkgs itself is pinned per environment (flake lock / channel revision), not "latest". - No NixOS model. No
configuration.nix, no system profiles, no Nix-managed services. Nix manages user environments only.
Rules
- Portage is the only authority over the running system. Nix and Flatpak never provide kernel, drivers, Mesa, PipeWire, systemd, core libraries or boot.
- Nix is user-level in effect. It provides developer tools and project environments, never system components.
- Never required. The system is fully functional with Portage alone; the base image and all services work if Nix is unused or removed.
- GUI apps go to Flatpak, not Nix.
- 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 installmeta-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
/nixstore; 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-daemonruns as root; it is a privileged component and must be treated as one (service hardening, update tracking).
Next steps
- Finish Flatpak integration:
xdg-desktop-portal(+-gtk/-wlrbackends), a documented app-install path, desktop integration. - Author the Phoebus overlay
sys-apps/nixebuild (+nix-daemon.service), install it from the installer, and verify in the disposable VM that a Nix dev environment works and the base system still boots without using it. - Add the
CreateDevEnvironmenttyped action with a bounded input set and tests. - Only then consider a thin
sys-level source chooser (not a generalpkg).