phoebus_os/installer
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
..
bin chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00
config chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00
doc chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00
lib chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00
tests chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00
tui chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00
README.md chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00

Phoebus OS installer

A deterministic, text-mode installer for Phoebus OS, inspired by void-installer. It is usable entirely without an LLM; AI only augments it.

Goals

  • Simple keyboard-driven TUI.
  • Logical, revisitable configuration stages.
  • A complete installation plan and explicit confirmation before anything destructive happens.
  • Logs for every backend operation.
  • No magical hidden disk modifications.

Two layers

tui/            front-end: menus, dialogs, screens
  menu.sh       main loop, review and install flow
  screens.sh    one function per configuration stage
  ui.sh         dialog/whiptail abstraction

lib/            deterministic backend (usable without the TUI)
  state.sh      structured configuration state
  logging.sh    logging + run_cmd + dry-run
  confirm.sh    destructive-operation authorization gates
  hardware.sh   read-only hardware probing
  disks.sh      read-only disk discovery and protection rules
  partitions.sh GPT partitioning
  filesystem.sh mkfs, mount, fstab/crypttab generation
  encryption.sh LUKS2
  btrfs.sh      subvolume layout
  network.sh    live networking + target hostname
  portage.sh    Portage configuration and stage3
  pkgpolicy.sh  compile-vs-binary policy
  kernel.sh     kernel profile and installation
  boot.sh       systemd-boot (BLS entries) + dracut initramfs
  users.sh      accounts, passwords, sudo
  desktop.sh    desktop profiles
  ai.sh         assistant and structured proposals
  opencode.sh   pinned, checksum-verified OpenCode
  plan.sh       installation plan generation
  validation.sh configuration validation
  install.sh    staged orchestration

config/
  defaults.conf        all defaults
  opencode.manifest    pinned OpenCode release + SHA-256

tests/                 unit tests, no root or disks required

Running in a Gentoo Live environment

The LiveGUI reference (or any Gentoo live medium with dialog, Portage and the disk tools listed in doc/FINDINGS.md) can run the installer directly:

sudo /path/to/installer/bin/ai-installer

Useful non-interactive modes (the backend works without the TUI):

# Print the generated installation plan and validate the configuration
ai-installer --plan

# Load a saved configuration
ai-installer --config /root/phoebus-install.conf

# Dry run: every command is logged, nothing is executed
ai-installer --dry-run

# Run the backend without a TUI (still requires explicit ERASE confirmation)
ai-installer --config /root/phoebus-install.conf --install

# Fetch and verify the pinned OpenCode release
ai-installer --bootstrap-opencode

Typical flow

  1. Network (connect Wi-Fi if needed).
  2. Keyboard, hostname, locale, timezone, user.
  3. Disk: pick a target (protected devices are never offered).
  4. Filesystem / encryption: LUKS2 is the default; set a passphrase.
  5. Boot / kernel / packages / desktop as desired.
  6. Review configuration -> inspect the plan.
  7. Install -> read the destructive summary, type ERASE, confirm again.

Safety model

  • Detection never modifies a disk.
  • The target disk must be explicitly selected from candidates.
  • Disks that are mounted, read-only, optical/loop, or back the live medium are marked PROTECTED and cannot be selected.
  • All destructive commands go through run_destructive, which refuses to run unless PHOEBUS_DESTRUCTIVE_AUTHORIZED=yes. Only install.sh grants this, only after the plan is approved.
  • Whole-disk erase additionally requires typing ERASE.
  • Dry-run mode redirects all file writes to a temporary sandbox and runs no commands.
  • Passwords, passphrases and API keys are never written to the config or logs.

Package policy

lib/pkgpolicy.sh implements the rule "compile when cheap or beneficial, use a binary when expensive and the benefit is negligible". It is deterministic and uses a curated table plus optional historical compile times ($STATE_DIR/compile-times.tsv). No model is consulted to guess performance.

AI policy

  • The normal install path is fully deterministic and LLM-free.
  • The AI assistant explains hardware, disks, filesystems, kernel and package choices, and can translate a natural-language request into a structured proposal (flat JSON with a fixed key whitelist).
  • Every proposed field is validated by lib/validation.sh. The LLM never receives secrets, never touches a disk and never runs a command.
  • Proposal flow: request -> proposal -> validation -> preview -> confirmation -> backend.

See doc/FINDINGS.md for environment findings and doc/TESTING.md for safe testing instructions.