phoebus_os/docs/adr/0006-package-lanes.md
Phoebus ab7408cdcf docs: make AI and Nix defining, offline-capable subsystems
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).
2026-09-20 14:27:02 -07:00

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.
  • 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

  1. 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 and nixbld build users, and installs a nix-daemon.service unit. The installer adds the overlay and emerges it as part of the base/desktop package set.
  2. Multi-user, system-managed. Because it is a real package, a root nix-daemon is acceptable: it is enabled like any other service, updated through emerge, and audited with the rest of the system.
  3. Pinned and verified. The ebuild pins the Nix version and verifies the upstream release tarball by SHA-256. The upstream curl | sh installer is never used. nixpkgs itself is pinned per environment (flake lock / channel revision), not "latest".
  4. No NixOS model. No configuration.nix, no system profiles, no Nix-managed services. Nix manages user environments only.

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: xdg-desktop-portal (+ -gtk/-wlr backends), a documented app-install path, desktop integration.
  2. Author the Phoebus overlay sys-apps/nix ebuild (+ 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.
  3. Add the CreateDevEnvironment typed action with a bounded input set and tests.
  4. Only then consider a thin sys-level source chooser (not a general pkg).