- Default natural-language and conversational routing for sys install, sys please install, and sys ask through shared AI workflow - Constrain AI candidate evaluation when source flags are supplied without bypassing the model - Enforce explicit --legacy flag for deterministic administration; legacy install without a source flag refuses execution and offers choices - Audit --action and --action-file entry points to require --legacy or --broker - Provide truthful guidance on absent or failing AI models without silent mutation or unverified fallback - Implement package correctness safeguards: Nix attribute evaluation probe, Portage binary check with source compile abort guard, cross-source installed application tracking, and data preservation on removal - Provide Quickshell desktop assistant (phoebus-assistant) backed by stdio JSON-RPC bridge (sys --assistant-bridge) and desktop integration - Implement unified multi-source update checking across all package lanes - Implement quiet proactive assistance monitor with alert deduplication and snoozing - Expand acceptance suite in installer/tests/vm/sys-acceptance.sh to 22 cases (22/22 PASS)
12 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
Desktop assistant GUI Quickshell/QML (installed; typed JSON-RPC protocol)
| phoebus-assistant
+-------------------+
|
Graphical welcome + installer Quickshell/QML (live only; typed JSON protocol)
| phoebus-welcome, phoebus-install
v 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 or administrative logic:
phoebus-installer --gui-bridgespeaks newline-delimited JSON on stdin/stdout, reuses the sameInstaller, plan, validation andDestructiveAuthorizationflow, and reports real stages throughInstaller::install_observed.sys --assistant-bridgespeaks newline-delimited JSON-RPC on stdin/stdout, providing a uniform interface for the desktop assistant (phoebus-assistant) for conversational interaction, legacy actions, unified updates, proactive alerts, and user preferences (ADR 0010, ADR 0013).
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, conversational parsing, and options.selection— hardware-aware source scoring, preference profiles (Balanced,FastInstallation,NativeIntegration,ApplicationIsolation), project tool environments, and candidate selection.update— unified multi-source update models across all supported package lanes.proactive— quiet proactive alert models, categories, and deferred schedules.brand— the visual identity (palette tokens, sun emblem, wordmark, wallpaper) as deterministic SVG/tokens shared by the QML frontend.
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.proactive— quiet proactive monitors for storage, services, transactions, and reboots.rollback— coordinated root/var/fstab/BLS rollback (ADR 0007).nix— pinned Nix bootstrap, attribute evaluation probe, sandboxed build config, and lifecycle.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.assistant_bridge— JSON-RPC stdio bridge serving the Quickshell desktop assistant.release—ReleaseManifestcreate/verify, candidate gates, atomic publish and signing command helpers.- Binaries:
phoebus-installer,sys,phoebus-release.
Safety model and package correctness
- 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.
- Portage binary vs source verification: Binary package recommendations are
verified with
emerge --pretend --usepkgonly. If a package would compile from source (EffectSource::Source), execution halts closed and demands a revised review and approval. - Nix attribute verification: Nix packages undergo evaluation probes against
<nixpkgs>before inclusion in recommendations or execution. - Cross-source ownership and data preservation: Installed applications are tracked across Portage, Flatpak, Snap, and AppImage. Removal preserves user data by default.
- Audited broker entry points: JSON action calls (
--action/--action-file) fail closed unless passed--legacyor--broker.
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.
Desktop assistant and administration architecture
The desktop assistant (phoebus-assistant) is an installed Quickshell GUI
application launched from the desktop menu, keybinding, or launcher:
- Shared execution core: The GUI contains no business logic. It communicates
via stdio JSON-RPC over
sys --assistant-bridge. - Recommendation cards and options: Recommends package sources with clear rationale (e.g., "Install Firefox from Flathub. Recommended because it avoids a lengthy build and provides application isolation"), expandable candidate comparisons, and single-approval execution bound to the plan digest.
- Unified multi-source updates: Queries and displays available updates across Portage, Flatpak, Snap, AppImage, and Nix, with reboot-required notifications.
- Quiet proactive monitoring: Periodically evaluates bounded deterministic health checks (service failures, disk usage under 5 GiB, failed transactions, pending updates), supporting deduplication, snooze, and user toggle.
- User preferences and profiles: Exposes inspectable preference profiles
(
Balanced,FastInstallation,NativeIntegration,ApplicationIsolation), per-project tool version mappings, and source pins. - Deterministic legacy panel: Structured GUI fallback controls executing
deterministic
--legacycommands directly through the bridge.
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.