Phoebus OS: a modern, stable, Gentoo-based workstation distribution - systemd, UEFI, LUKS2, Btrfs snapshots, Wayland, Flatpak, optional AI admin assistant.
Find a file
2026-09-22 07:30:38 -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 fix(sys): harden the administration broker and complete its command surface 2026-09-22 07:30:38 -07:00
installer fix(installer): do not discard the validated AI state on unrelated edits 2026-09-22 04:13:31 -07:00
installer-rs fix(sys): harden the administration broker and complete its command surface 2026-09-22 07:30:38 -07:00
scripts docs: update references after retiring the Bash installer 2026-09-20 04:00:19 -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.