Some checks are pending
ci / test (push) Waiting to run
sys install <name>, sys remove <name> and sys search <query> are deterministic and model-free: Portage resolves a bare name or a full atom. Adds the remove_package and search_packages typed actions (remove is High risk and gets the protective snapshot; search is read-only). This is the old-fashioned fallback so the system stays fully administrable with no LLM.
124 lines
4.4 KiB
Rust
124 lines
4.4 KiB
Rust
# 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 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
|
|
|
|
```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
|
|
```
|
|
|
|
Formatting and lints are part of the gate:
|
|
|
|
```sh
|
|
cargo fmt --all -- --check
|
|
cargo clippy --workspace --all-targets
|
|
```
|
|
|
|
## 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/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.
|