phoebus_os/docs/adr/0008-nix-isolation-lifecycle.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

3.9 KiB

ADR 0008: Nix lifecycle, build isolation, and packaging

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

Context

The first Nix bootstrap wrote sandbox = false, and the lifecycle (upgrade, removal, store cleanup) was undefined. ADR 0006 claimed a normal binary ebuild is impossible because the upstream installer hardcodes /nix, calls sudo and uses nix-store --load-db with no DESTDIR. That claim was re-examined rather than assumed.

Decision

Build isolation is on and does not silently fall back

/etc/nix/nix.conf now sets:

sandbox = true
sandbox-fallback = false
auto-optimise-store = true
min-free  = 1073741824
max-free  = 10737418240

The Nix sandbox uses Linux user namespaces. sandbox-fallback = false means a build that cannot be sandboxed fails instead of silently building with host access. This is the same principle as "never weaken a protection for convenience": a build-time sandbox that can be transparently disabled provides no guarantee. The Phoebus kernel (distribution kernel plus the conservative fragments) includes CONFIG_USER_NS.

min-free/max-free bound the store so /nix cannot fill the root filesystem; auto-optimise-store deduplicates.

Store cleanup and rollback interaction

  • /nix lives inside @, so a system rollback restores the store together with the OS package state. This is intended: the Nix store is OS state.
  • Garbage collection is explicit (nix-store --gc, bounded by min-free/ max-free), never automatic on a timer.
  • Removing Nix removes the daemon units and profile wiring; purging the store is a separate, explicit choice, because it also removes user environments.

Portage-managed lifecycle

The requirement is that Portage owns Nix: installation, upgrades, daemon integration and removal. The upstream installer's lack of DESTDIR blocks a conventional binary ebuild, but it does not block an ebuild that performs the same bootstrap the installer performs:

  • src_unpack fetches the pinned, SHA-256-verified release tarball.
  • src_install copies the release's store/ into ${D} (the ebuild's image), so the files are package-owned.
  • pkg_postinst runs nix-store --load-db against the live root, creates the nixbld group/users, and enables nix-daemon.service/.socket.

This is a bootstrap-style ebuild, not a DESTDIR install of a build tree; it is the standard technique for packages that must initialise state at install time (the same shape as sys-apps/portage's news/env-update handling). It belongs in the Phoebus overlay as sys-apps/nix.

Until the overlay ebuild is published, the installer provisions the same lifecycle directly (discrete, no curl | sh, no sh -c), and the runtime lifecycle operations are implemented in phoebus-executor::nix: install, remove(purge), gc, and valid_nix_attribute for bounded developer-package realisation. sys exposes nix_prepare { packages } as a bounded typed action.

Authority

Nix remains a developer lane only (ADR 0006): no core component, service, library or boot path depends on it. Portage owns the kernel, drivers, systemd, Mesa, PipeWire, core libraries and the boot stack.

Consequences

  • A build that needs user namespaces now fails closed where they are absent.
  • The store is bounded; growth is visible and managed.
  • The overlay ebuild is the remaining Portage-ownership step; it is documented and its lifecycle is already exercised by the installer and nix_* operations. It is not yet shipped in a repository.

Verification

  • Unit tests assert the generated /etc/nix/nix.conf enables the enforced sandbox and store bounds, and that removal unlinks units and only purges on request.
  • VM verification of a sandboxed source build (nix build of a package with a derivation that would fail without isolation) and of the ebuild lifecycle is recorded in docs/STATUS.md as outstanding.