Phoebus OS: a modern, stable, Gentoo-based workstation distribution - systemd, UEFI, LUKS2, Btrfs snapshots, Wayland, Flatpak, optional AI admin assistant.
Find a file
Phoebus 3b1b54ffb9
Some checks are pending
ci / test (push) Waiting to run
docs: reconcile NVIDIA, verification and harness status
Record the reliability pass across STATUS, HANDOFF, CHANGELOG, ADR 0012,
the live README and the boot-verification log: the deterministic live GPU
decision with a real nouveau fallback, the 580 legacy cap and mixed
open/proprietary incompatibility, the compatibility verifier, the
installed lifecycle fix, the repaired GUI harness, the automated but
unrun rollback gate, and the scoped live sudoers. Withdraw the stale
handoff claim that the gui_bridge tests hang (the workspace suite
passes) and record the installed-target missing-sys gap.
2026-09-23 06:28:30 -07:00
.forgejo ci: make the Rust suite the only quality gate 2026-09-20 03:57:01 -07:00
.githooks ci: make the Rust suite the only quality gate 2026-09-20 03:57:01 -07:00
.opencode ci: make the Rust suite the only quality gate 2026-09-20 03:57:01 -07:00
docs docs: reconcile NVIDIA, verification and harness status 2026-09-23 06:28:30 -07:00
installer docs: reconcile NVIDIA, verification and harness status 2026-09-23 06:28:30 -07:00
installer-rs fix(live): scope the live privilege policy to the typed brokers 2026-09-23 06:22:19 -07:00
scripts feat(nvidia): hardware-driven driver policy, installed integration and live payload 2026-09-22 21:53:28 -07:00
.gitattributes feat(git): add session context, host doctor, ADRs and git hygiene 2026-09-20 02:36:32 -07:00
.gitignore feat(live): build a Debian-Live installer appliance ISO (no root) 2026-09-20 12:49:31 -07:00
AGENTS.md docs: one control plane — sys typed actions, not raw Portage 2026-09-20 14:35:05 -07:00
LICENSE feat(git): add license, opencode project config and branch protection 2026-09-20 02:41:35 -07:00
Makefile feat(gui): select and validate OpenCode from the installer 2026-09-22 02:36:36 -07:00
README.md feat(live): build a Debian-Live installer appliance ISO (no root) 2026-09-20 12:49:31 -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/live/    Debian-Live installer appliance ISO recipe
installer/tests/vm/ disposable UEFI VM harness (static Rust binary)
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

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.
  • docs/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.