phoebus_os/installer-rs
Phoebus e82aaba5fb fix(executor): fail closed when a protective snapshot cannot be created
High-risk sys actions now create their protective snapshot inside
actions::execute and abort if the .snapshots subvolume exists but the snapshot
fails, instead of warning and mutating anyway. Corrupt snapshot history is
surfaced as an error rather than being silently treated as empty.
2026-09-20 04:39:23 -07:00
..
crates fix(executor): fail closed when a protective snapshot cannot be created 2026-09-20 04:39:23 -07:00
Cargo.lock feat(rust): port OpenCode provisioning with verified checksums 2026-09-20 03:00:30 -07:00
Cargo.toml chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00
README.md test(rust): replace the Bash parity test with golden plan tests 2026-09-20 03:56:57 -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 --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.