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). |
||
|---|---|---|
| .. | ||
| crates | ||
| Cargo.lock | ||
| Cargo.toml | ||
| README.md | ||
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::snapshotdefines deterministic snapshot names and a TOML transaction history.phoebus-executor::snapshotcreates read-only Btrfs snapshots./homeis intentionally not snapshotted by default.phoebus-core::update/phoebus-executor::updateimplement preparation only:emerge --fetchonlythenemerge --buildpkgonlystage 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. TargetRootrejects absolute paths and..traversal, so host-versus-target bugs are caught by construction and covered by tests.- Destructive functions require a
DestructiveAuthorizationtoken produced only after the ERASE confirmation and a final confirmation. phoebus-aican 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.