Phoebus OS: a modern, stable, Gentoo-based workstation distribution - systemd, UEFI, LUKS2, Btrfs snapshots, Wayland, Flatpak, optional AI admin assistant.
Find a file
Phoebus 54701bd1ef test(vm): record static-binary install and detached boot evidence
The committed harness now installs with the static Rust binary and boots the
disk detached: systemd PID1, running, 0 failed units, LUKS2 unlock, login and
networking. Also fixes the boot check marker so expect() does not match the
shell's echoed command.
2026-09-20 03:54:53 -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 test(vm): record static-binary install and detached boot evidence 2026-09-20 03:54:53 -07:00
installer test(vm): record static-binary install and detached boot evidence 2026-09-20 03:54:53 -07:00
installer-rs feat(rust): port OpenCode provisioning with verified checksums 2026-09-20 03:00:30 -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.