Phoebus OS: a modern, stable, Gentoo-based workstation distribution - systemd, UEFI, LUKS2, Btrfs snapshots, Wayland, Flatpak, optional AI admin assistant.
Find a file
Phoebus e82aaba5fb fix(executor): fail closed when a protective snapshot cannot be created
High-risk sys actions now create their protective snapshot inside
actions::execute and abort if the .snapshots subvolume exists but the snapshot
fails, instead of warning and mutating anyway. Corrupt snapshot history is
surfaced as an error rather than being silently treated as empty.
2026-09-20 04:39:23 -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(migration): record Phases 0-4 complete in the session log 2026-09-20 04:01:03 -07:00
installer/tests/vm refactor!: retire the Bash installer tree and relocate its docs 2026-09-20 04:00:14 -07:00
installer-rs fix(executor): fail closed when a protective snapshot cannot be created 2026-09-20 04:39:23 -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 chore: import Phoebus OS installer and Rust migration 2026-09-20 02:07:33 -07:00
AGENTS.md docs: update references after retiring the Bash installer 2026-09-20 04:00:19 -07:00
LICENSE feat(git): add license, opencode project config and branch protection 2026-09-20 02:41:35 -07:00
Makefile ci: make the Rust suite the only quality gate 2026-09-20 03:57:01 -07:00
README.md docs: update references after retiring the Bash installer 2026-09-20 04:00:19 -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/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.