phoebus_os/installer-rs/README.md
Phoebus 38214ea9e7 chore: import Phoebus OS installer and Rust migration
Initial public import of the proven Bash installer (installer/) and the production Rust workspace (installer-rs/). The reference ISO, build output and local agent transcripts are gitignored.

Verified: installer/tests/run_tests.sh and cargo test --workspace both pass.
2026-09-20 02:07:33 -07:00

114 lines
4.1 KiB
Markdown

# 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.