# 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`).