The guest script now fetches and runs the static phoebus-installer binary instead of the Bash tree, keeping the 0600 secret files and NO_SECRET_LEAK scan. Docs and the interactive launcher point at the Rust binary. |
||
|---|---|---|
| .. | ||
| bin | ||
| config | ||
| doc | ||
| lib | ||
| tests | ||
| tui | ||
| README.md | ||
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
- Network (connect Wi-Fi if needed).
- Keyboard, hostname, locale, timezone, user.
- Disk: pick a target (protected devices are never offered).
- Filesystem / encryption: LUKS2 is the default; set a passphrase.
- Boot / kernel / packages / desktop as desired.
- Review configuration -> inspect the plan.
- 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 unlessPHOEBUS_DESTRUCTIVE_AUTHORIZED=yes. Onlyinstall.shgrants 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.