A binary ebuild is impossible (the upstream installer has no DESTDIR and runs nix-store --load-db against the real root), so bootstrap the pinned, SHA-256-verified official release with discrete commands in the target chroot (no curl|sh, no sh -c): store copy, DB load, nixbld users, profile wiring and nix-daemon units. Gated behind packages.nix (default off) until VM-verified.
141 lines
6.5 KiB
Markdown
141 lines
6.5 KiB
Markdown
# 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
|
|
|
|
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. **Gated until verified.** `packages.nix` defaults off until a disposable-VM
|
|
install confirms the bootstrap; Nix never becomes a hard dependency.
|
|
|
|
## 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`).
|