Unifies AI-first administration across the CLI (sys) and desktop GUI
(phoebus-assistant) through a shared service layer, fixes installed
desktop QML asset provisioning, adds Polkit elevation, and introduces
contextual conversation continuity.
- Extract phoebus_installer::service shared by CLI and desktop assistant bridge:
- Reviewable plan staging (PreparedPlan) with SHA-256 cryptographic digests,
15-minute TTL expiration, and replay prevention (PlanStore).
- Pre-mutation system state revalidation binding execution strictly to the reviewed plan.
- Honest recommendations displaying genuine provenance and unmeasured compile times.
- Two-phase transaction logging (begin before mutation, finish with verification).
- Provision installed desktop assets and Polkit policy in phoebus-executor::desktop:
- Added gui-apps/quickshell to canonical Mango desktop packages.
- Embed 13 QML and policy files into target root under /usr/share/phoebus/assistant/.
- Installed Polkit policy (club.phoebus.sys.policy) allowing unprivileged users to
authenticate mutating plans via pkexec without blanket passwordless sudo.
- Eliminate startup freeze and polling in phoebus-assistant:
- Multi-source update queries moved to on-demand tab switching.
- Handshake timer reduced to one-shot 100ms with fast deterministic check.
- Add phoebus_installer::conversation:
- Bounded 10-turn history with credential redaction.
- Contextual follow-up resolution for comparisons, backend switching, and confirmation.
- Implement unified cross-source removal (plan_removal) preserving user data by default.
- Verified: all 486 workspace tests pass, release and crt-static builds succeed,
and 23/23 VM acceptance cases pass (PASS=23 FAIL=0).
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.service— shared administration service layer (PreparedPlan,PlanStore, planning, authorization, Polkit elevation, execution, and verification) shared identically by CLI and GUI.conversation— bounded conversation history and contextual follow-up resolution (tradeoff comparisons, backend switching, and plan confirmation).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.