Phoebus OS: a modern, stable, Gentoo-based workstation distribution - systemd, UEFI, LUKS2, Btrfs snapshots, Wayland, Flatpak, optional AI admin assistant.
Find a file
Phoebus 4c59a1f3ad test(rust): replace the Bash parity test with golden plan tests
parity.rs compared the Rust plan to the Bash installer. The Bash tree is
being retired, so pin the exact Rust plan and destructive preview to golden
files instead (UPDATE_GOLDEN=1 to regenerate).
2026-09-20 03:56:57 -07:00
.forgejo docs(git): hardening docs, backup timer and issue/PR templates 2026-09-20 02:42:50 -07:00
.githooks feat(git): add session context, host doctor, ADRs and git hygiene 2026-09-20 02:36:32 -07:00
.opencode chore(docs): add evidence-gated Bash migration plan 2026-09-20 02:57:13 -07:00
docs docs(migration): pin the Phase 2 evidence commit 2026-09-20 03:55:12 -07:00
installer test(vm): record static-binary install and detached boot evidence 2026-09-20 03:54:53 -07:00
installer-rs test(rust): replace the Bash parity test with golden plan tests 2026-09-20 03:56:57 -07:00
scripts docs(git): hardening docs, backup timer and issue/PR templates 2026-09-20 02:42:50 -07:00
.gitattributes feat(git): add session context, host doctor, ADRs and git hygiene 2026-09-20 02:36:32 -07:00
.gitignore chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00
AGENTS.md feat(git): add session context, host doctor, ADRs and git hygiene 2026-09-20 02:36:32 -07:00
LICENSE feat(git): add license, opencode project config and branch protection 2026-09-20 02:41:35 -07:00
Makefile feat(git): add license, opencode project config and branch protection 2026-09-20 02:41:35 -07:00
README.md feat(git): add license, opencode project config and branch protection 2026-09-20 02:41:35 -07:00

Phoebus OS

A modern, stable, Gentoo-based workstation operating system: systemd, Wayland-first, PipeWire, UEFI/GPT, LUKS2, Btrfs with snapshots, a fast dwl-style desktop, Flatpak, and an optional AI administration assistant. AI-first, never AI-dependent.

Stability first: modern architecture + mature implementations + conservative updates + recovery.

Status

A complete encrypted UEFI install has been built and booted in a disposable VM (ISO detached): GPT + LUKS2 + Btrfs, systemd PID 1, login, networking, and a verified Wayland desktop stack with Flatpak. See docs/STATUS.md for the exact implementation/verification matrix and known limitations.

Repository layout

AGENTS.md          entry point for AI/human contributors (read first)
docs/              objectives, roadmap, status, architecture, process
installer/         proven Bash installer (reference / fallback) + VM harness
installer-rs/      production Rust installer (crates/ workspace)
scripts/           git/dev tooling (hooks, publish, agent-commit)
.githooks/         committed git hooks

The Gentoo LiveGUI ISO is a reference artifact and is not tracked by git.

Build and test

# Bash reference
installer/tests/run_tests.sh

# Rust production installer
cd installer-rs
cargo fmt --all -- --check
cargo clippy --workspace --all-targets
cargo test --workspace
cargo build --release -p phoebus-installer

Installer quick start (Rust):

phoebus-installer --config FILE --plan       # installation plan
phoebus-installer --config FILE --dry-run    # no system changes
phoebus-installer --config FILE --install    # run the backend
phoebus-installer --config FILE --install --yes \
    --luks-passphrase-file /secure/luks.pw \
    --user-password-file /secure/user.pw

The normal installation path is entirely deterministic and does not require an LLM. AI is an optional assistant that proposes typed, validated changes which the user approves; it never holds root or a shell.

Documentation

  • docs/OBJECTIVES.md — vision, philosophy, non-goals.
  • docs/ROADMAP.md — priorities and current status.
  • docs/STATUS.md — implemented / unit-tested / VM-verified.
  • docs/ARCHITECTURE.md — components and safety model.
  • docs/DEVELOPMENT.md — host setup, build, VM testing.
  • docs/CONTRIBUTING.md — standards and definition of done.
  • docs/GIT-WORKFLOW.md — how to commit, push and release.
  • installer/doc/VM-BOOT-VERIFICATION.md — boot evidence.

License

Phoebus OS is licensed under the GNU General Public License, version 2 or later (GPL-2.0-or-later). See LICENSE.