- Excised standalone dwl packages: gui-wm/dwl, waybar, wofi, mako, swaybg, swayidle, swaylock - Removed standalone dwl session and helper assets: PHOEBUS_SESSION_SCRIPT, PHOEBUS_MENU_SCRIPT, PHOEBUS_LOCK_SCRIPT, PHOEBUS_IDLE_SCRIPT, WAYBAR_CONFIG, WAYBAR_STYLE, phoebus-dwl.desktop - Consolidated DesktopProfile enum to Mango (default) and None (headless), rejecting legacy dwl configurations - PHOEBUS_MANGO_SESSION_SCRIPT (/usr/local/bin/phoebus-session-mango) fails visibly/diagnostically on error without silent fallback - Provided /usr/local/bin/phoebus-session as a direct wrapper to phoebus-session-mango - Live ISO emitted assets reduced from 24 to 17 and verified clean
8.6 KiB
Architecture
Phoebus ships one installer implementation: the Rust workspace in
installer-rs/. It reproduces the proven encrypted UEFI VM boot path and is the
only implementation on the install path. The retired Bash prototype is kept in
git history, tagged v0.1.0-bash-reference; see docs/BASH-MIGRATION.md for
the evidence-gated retirement.
The disposable VM harness lives in installer/tests/vm/ and drives the static
Rust binary.
Layering
Graphical welcome + installer Quickshell/QML (live only; typed JSON protocol)
| phoebus-welcome, phoebus-install
v
TUI / CLI / sys front-ends (phoebus-tui, phoebus-installer)
|
v
Orchestration + plan staged execution, single source of truth
|
v
Executor commands, storage, Portage, boot, services
|
v
Core typed config, models, policy, validation
The graphical frontend is one of several front-ends; it never contains
installation logic. phoebus-installer --gui-bridge speaks newline-delimited
JSON on stdin/stdout, reuses the same Installer, plan, validation and
DestructiveAuthorization flow, and reports real stages through
Installer::install_observed. The QML only renders typed state and submits
bounded requests (ADR 0010).
phoebus-core
Pure, non-privileged logic with no external commands except reading /proc,
/sys and small system files:
config—InstallConfig(nested sections, enums for closed sets); TOML and legacy flat-format loading (format is detected structurally).validate— hostname/username/locale/timezone/keymap/password checks.disk/hardware— models and protection classification (pure).plan—InstallPlanwith the canonical step order and human rendering.policy— deterministic source/binary decisions + policy context.emergelog— parses Portageemerge.loginto measured compile times.target—TargetRoot, which rejects absolute paths and..traversal.secret—SecretString(redactedDebug, zeroized on drop) +Redactor.snapshot— deterministic snapshot names + TOML transaction history.boot— BLS entry parse/render and root-subvolume selection for rollback.rollback— rollback state machine, retention and mount/fstab planners.effects— parseemerge --pretendinto resolved effects + plan digest.transaction— the user-queryable log of executed actions and outcomes.action— closedSystemActionschema and a small deterministic parser.brand— the visual identity (palette tokens, sun emblem, wordmark, wallpaper) as deterministic SVG/tokens shared by the QML frontend.update— preparation policy and real Portage argument builders.
phoebus-executor
The only crate that runs privileged commands.
command—CommandSpec,ProcessRunner(real / recording / never) with arguments always separate; there is nosh -c.exec—Execcentralises logging, redaction, dry-run, chroot mounts and target writes.log— file + optional stderr logging; every line is redacted.auth—DestructiveAuthorization, issued only after ERASE + final confirmation.storage,encryption,portage,kernel,boot,users,services,desktop— the install backend, mirroring the proven order.probe— read-only hardware and disk discovery.snapshot,update,admin,actions— post-install foundations.rollback— coordinated root/var/fstab/BLS rollback (ADR 0007).nix— pinned Nix bootstrap, sandboxed build config, lifecycle and cleanup.sandbox— the hardenedsystemd-runboundary for model execution.transaction— persists the transaction log into the target.
phoebus-ai
- Typed
AiProposal/SystemAction(unknown actions fail closed; no shell). assistant— the installed conversational plan schema (AssistantPlan) and its fail-closed parser; the model proposes the same actionssysexecutes.privacy—PrivacyPolicy+ContextBundle; forbidden-path checks. The collector inphoebus-executor::adminonly reads system sources.
phoebus-installer
orchestrate—Installerruns the plan stages and stops on first failure.release—ReleaseManifestcreate/verify, candidate gates, atomic publish and signing command helpers.- Binaries:
phoebus-installer,sys,phoebus-release.
Safety model
- Every command goes through
Exec, which logs a redacted command line, exit status and duration, and honours dry-run centrally. - Destructive functions take
&DestructiveAuthorization; the token is created only after the destructive preview and confirmations. - All target writes go through
TargetRoot; host-versus-target mistakes are caught by construction and covered by tests. - Secrets travel over stdin only and are registered with the redactor before any logging. They never enter the config.
- The AI cannot execute; it can only propose typed changes that the backend
validates and the user approves. The assistant's model call additionally runs
inside an unprivileged, hardened
systemd-rununit (sandbox), so the boundary is enforced by the OS and not only by the schema. - Approval is bound to the reviewed resolved plan: package effects are resolved again before execution and a material change aborts.
Rollback and recovery
A recovery point is a snapshot set: @ and the separate @var (Portage state)
together; /home is excluded. Rollback creates a writable root generation,
rewrites subvol= in both the restored root's fstab and the BLS entry options
(the explicit argument overrides the Btrfs default), selects a kernel entry
whose modules match the restored root, and writes previous/recovery entries.
See ADR 0007.
Desktop environment: Mango + DarkMaterial
Phoebus OS has one desktop experience only: Mango + DarkMaterial (desktop.profile = "mango").
- Mango + DankMaterialShell:
gui-wm/mangowm(a wlroots-based tiling compositor) plus the DMS shell (panel, launcher, notifications, lock, idle, audio/network/Bluetooth/display controls) from the GURU overlay. - Entry points: Session entry point
/usr/local/bin/phoebus-session-mango(with convenience wrapper/usr/local/bin/phoebus-session), session file/usr/share/wayland-sessions/phoebus-mango.desktop. - Display Manager:
greetdwithtuigreetconfigured to launch the canonical session upon authentication. - Headless: Systems requiring no graphical desktop can set
desktop.profile = "none".
desktop.profile selects both the Gentoo desktop/systemd profile and the package set; the plan displays the canonical desktop session before installation.
Installation order (do not regress)
storage_prepare -> stage_install -> fstab_generate -> portage_configure
-> packages_base -> kernel_install -> boot_install -> users_configure
-> services_configure -> desktop_install -> finalize
Storage order: partition GPT, create ESP, LUKS format/open, mkfs.btrfs, mount
top-level, create subvolumes, unmount, mount the subvolume layout. fstab and
crypttab are generated after stage3 extraction (stage3 ships its own
/etc/fstab).
Configuration and plan
InstallConfig is canonical data; the plan and all rendering derive from it.
The same plan drives the review screen, the destructive preview, dry-run and
the actual execution, so the UI cannot diverge from the backend.
Post-install foundations
- Snapshots: read-only Btrfs snapshots under
/.snapshots, recorded in a TOML history. A snapshot set captures@and the separate@var;/homeis intentionally not snapshotted so user documents survive a rollback. - Rollback:
sys undorestores a committed snapshot as the next boot root with coordinated fstab, BLS and kernel selection (ADR 0007); a persisted state file makes an interrupted rollback resumable. - Background updates:
emerge --fetchonlythen--buildpkgonlystage distfiles and reusable local binary packages without installing; activation stays explicit. - Kernel/boot:
sys-kernel/gentoo-kernel-bin(safe) orgentoo-kernel(optimized), dracut initramfs, systemd-boot BLS entries, plus a snapshot-based recovery entry that does not depend on the live root.
Extension points
ProcessRunner— swap the real runner for a recording/never runner in tests, or for a different execution backend.InstallStep— add stages inplan.rsand handle them inorchestrate.rs.SystemAction— add closed verbs; the policy engine classifies and previews them, and the broker executes them after approval.