Phoebus OS: a modern, stable, Gentoo-based workstation distribution - systemd, UEFI, LUKS2, Btrfs snapshots, Wayland, Flatpak, optional AI admin assistant.
Find a file
Phoebus a6ed363745
Some checks are pending
ci / test (push) Waiting to run
test(selection): cover divergent machines and the extended prompt
- add policy tests for missing hardware information, limited storage choosing
  the smaller candidate, and the same application resolving to Portage binary,
  source or Flatpak depending on the machine, preference and sandbox
  requirement.
- drop the always-on strong-sandbox bonus to a mild +3 so GUI apps are not
  effectively routed to Flatpak by category (ADR 0006 revision intent).
- keep the assistant prompt and a plan-acceptance test in sync with the
  extended action schema (choose_package, set_package_preference, snap_*,
  appimage_acquire, custom_ebuild_prepare).
2026-09-23 18:38:59 -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 feat(sys): hardware-aware lane selection and new lanes 2026-09-23 18:35:26 -07:00
installer feat(sys): hardware-aware lane selection and new lanes 2026-09-23 18:35:26 -07:00
installer-rs test(selection): cover divergent machines and the extended prompt 2026-09-23 18:38:59 -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 feat(sys): hardware-aware lane selection and new lanes 2026-09-23 18:35:26 -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.