phoebus_os/installer-rs
Phoebus f9e39925b4 feat(install): AI-first sys install workflow
Implement the shared installation workflow (ADR 0013). sys install, sys ask
install and the explicit backend flags all use one path: identify -> evidence
-> AI investigation -> deterministic validation/effects -> review -> approval
-> execute -> verify -> history.

- phoebus-ai::install: bounded, multi-turn investigation. The model may request
  typed read-only evidence (discover_candidates, inspect_candidate,
  check_backend, inspect_installation), ask one bounded question about intent,
  and must return a structured InstallProposal. Turn/request/size limits and
  repeated-request detection bound it; a rejected proposal is revised.
- phoebus-core: add the four read-only investigation actions and strict
  validators; add a transaction id; backend/kind wire names now match as_str.
- phoebus-executor::install: resolve_explicit (no model, no fallback),
  resolve_deterministic and resolve_with_ai; validate_proposal re-resolves the
  candidate against real metadata, rejects fabrication/ambiguity/staleness/
  duplicates, maps it to the existing broker action, and binds approval to a
  digest; revalidate + verify_installed. chooser gains per-lane friendly-name
  resolution and structured evidence.
- transaction::begin/finish record an in-progress transaction before mutation.
- sys: --portage/--flatpak/--nix/--snap/--appimage/--ebuild (mutually
  exclusive) bypass the model; an unqualified install consults the model and,
  with none, prints the deterministic selection and installs nothing.
- The installer persists /etc/phoebus/install.toml; sys loads it and adds free
  space, Wayland, usable lanes, saved preferences and recovery capability to
  the bounded facts.
- Docs: ADR 0013, docs/SYS.md install sections and cases 23-31, CHANGELOG,
  STATUS, HANDOFF, ROADMAP. New live-VM workflow check script.

Host gates pass: fmt, clippy (no new warnings), workspace tests, make test.
VM: verified the workflow CLI and read-only investigation on the reference
LiveGUI ISO; a full target install journey is running (see HANDOFF).
2026-09-23 20:30:13 -07:00
..
crates feat(install): AI-first sys install workflow 2026-09-23 20:30:13 -07:00
Cargo.lock feat(desktop): add Mango + DankMaterialShell profile with rollback, assistant and release foundations 2026-09-21 03:46:52 -07:00
Cargo.toml chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00
README.md feat(sys): add offline Portage install/remove/search commands 2026-09-20 14:28:35 -07:00

Phoebus OS installer (Rust)

The production installer/backend for Phoebus OS. It is being built beside the proven Bash implementation and only becomes primary once it reproduces the known-good encrypted UEFI VM boot.

Workspace

crates/
  phoebus-core       configuration types, validation, plan, package policy,
                     hardware/disk models, target-root safety, secrets,
                     snapshot history, typed system actions, update policy
  phoebus-executor   command runner, logging, storage, encryption, Btrfs,
                     stage3, Portage, kernel, boot, users, services, desktop,
                     snapshots, background-update preparation, admin context
  phoebus-ai         typed AI proposals + enforced privacy boundary
  phoebus-tui        ratatui terminal UI
  phoebus-installer  CLI, `sys`, orchestration

Binaries: phoebus-installer (installer) and sys (typed system interface).

sys

sys enable sshd                       # deterministic phrase -> typed action
sys disable bluetooth
sys history                           # snapshot/transaction history
sys what are you compiling            # background update status
sys install vim                       # Portage (bare name or category/name)
sys search firefox
sys remove vim
sys --action '{"action":"inspect_service","name":"ssh"}'
sys --action-file proposal.json       # the AI path: same typed schema

Mutating actions require root (run under sudo); the model never receives the password. High-risk actions are preceded by a Btrfs snapshot when available. There is no run_shell action; unknown actions fail closed.

Snapshots and background updates

  • phoebus-core::snapshot defines deterministic snapshot names and a TOML transaction history. phoebus-executor::snapshot creates read-only Btrfs snapshots. /home is intentionally not snapshotted by default.
  • phoebus-core::update / phoebus-executor::update implement preparation only: emerge --fetchonly then emerge --buildpkgonly stage distfiles and reusable local binary packages without installing. Activation stays explicit.

Building

cargo test --workspace
cargo build --release -p phoebus-installer

# A static binary is preferred for the live installer environment:
RUSTFLAGS="-C target-feature=+crt-static" \
  cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu

Formatting and lints are part of the gate:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets

CLI

phoebus-installer --config FILE --plan
phoebus-installer --config FILE --dry-run --install
phoebus-installer --config FILE --install --yes \
    --luks-passphrase-file /run/luks.pw \
    --user-password-file /run/user.pw

Both TOML and the legacy flat KEY='value' format are supported. Format is detected structurally (the flat format is also valid TOML because single quotes are TOML literal strings).

[system]
hostname = "phoebus"
timezone = "UTC"

[storage]
disk = "/dev/vda"
filesystem = "btrfs"

[encryption]
mode = "luks2"

Secrets are never stored in the configuration. They are supplied through 0600 files and registered with the redactor before anything is logged.

Safety model

  • Every command goes through phoebus-executor::Exec, which logs redacted arguments, exit status and duration, and honours dry-run centrally.
  • Arguments are always passed separately; there is no sh -c.
  • TargetRoot rejects absolute paths and .. traversal, so host-versus-target bugs are caught by construction and covered by tests.
  • Destructive functions require a DestructiveAuthorization token produced only after the ERASE confirmation and a final confirmation.
  • phoebus-ai can only emit a closed set of typed configuration changes; unknown actions fail closed and there is no shell action.

Package policy

phoebus-core::policy implements the deterministic source/binary rule and records measured compile times parsed from Portage's emerge.log (phoebus-core::emergelog). No performance value is ever invented.

Verification

crates/phoebus-installer/tests/plan_golden.rs pins the rendered plan and destructive preview to golden files under tests/golden/ (regenerate with UPDATE_GOLDEN=1). crates/phoebus-installer/tests/cli_coverage.rs pins the command-line surface to the reference Bash installer. The disposable VM harness in ../installer/tests/vm drives the static binary through a full encrypted install and boot.