# 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` ```sh sys enable sshd # deterministic phrase -> typed action sys disable bluetooth sys history # snapshot/transaction history sys what are you compiling # background update status 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 ```sh 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 ``` `rustfmt` and `clippy` are not available in the reference toolchain used for this milestone. ## CLI ```sh 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). ```toml [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/parity.rs` compares the Bash and Rust plans for the same configuration. The disposable VM harness in `../installer/tests/vm` drives the static binary through a full encrypted install and boot.