phoebus_os/docs/OBJECTIVES.md
Phoebus 0c2a6bb9d6
Some checks are pending
ci / test (push) Waiting to run
docs: require an AI at install; AI-first system, legacy fallback
Installing Phoebus now requires a connected model (remote provider or a
user-downloaded local model; none is shipped). The installed system is AI-first
and uses a connected model proactively. It is never required to boot, run or
recover: the deterministic CLI (sys, emerge, nix, flatpak) remains as a
break-glass fallback, and no model ever holds privilege.
2026-09-20 14:33:19 -07:00

4.8 KiB

Objectives

Vision

Phoebus OS is a modern, stable, Gentoo-based workstation operating system that provides Gentoo-level flexibility, performance and control without requiring the user to act as a full-time Gentoo administrator.

It combines a mature modern architecture with a conservative update policy and real recovery:

Modern architecture + mature implementations
+ conservative updates + snapshots/rollback

Pillars

  • Gentoo + Portage remain the package foundation. Phoebus is an integration layer, not a parallel Linux ecosystem.
  • systemd is the init and service architecture; OpenRC is out of scope.
  • Wayland-first, with XWayland only for compatibility.
  • PipeWire + WirePlumber are the audio stack. PulseAudio is not the target.
  • UEFI/GPT-first. Legacy BIOS is not a v0.1 priority.
  • LUKS2 whole-root encryption with a passphrase (TPM2 later, never mandatory).
  • Btrfs with subvolumes, snapshots and (eventually) rollback.
  • Stability over novelty. Stable/LTS kernels, mature filesystems, no release candidates, no globally unmasked testing tree.
  • Pragmatic builds. Compile when it is cheap or genuinely beneficial; use signed Gentoo binaries when compilation is expensive and the benefit is negligible.
  • Friendly to proprietary software (drivers, firmware, codecs, Steam, browsers) where legally distributable. No moralising warnings; respect licences.
  • AI-first, by design. The assistant and Nix are defining, always-present subsystems, not optional add-ons. Installing Phoebus requires an AI: the installer will not complete without a connected model (a remote provider, or a local model the user downloads; Phoebus ships none). The installed system is AI-first — the assistant is the primary interface, and while a model is connected the system uses it proactively. Legacy commands (sys, emerge, nix, flatpak) always remain so the system can be operated and repaired by hand if the AI is unavailable; nothing bricks.
  • Nix as a second, built-in package lane. Portage stays authoritative for the system (kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot, services); Nix provides developer tools, alternate versions and reproducible per-project environments. Nix is shipped and updated through Portage, never as a curl | sh artifact.

The AI contract

The LLM is an interface, explainer, planner and reasoning assistant. It is not the source of truth, the root shell, or the privilege boundary.

user request -> LLM -> typed structured action -> policy engine
-> human-readable preview -> explicit approval -> authentication
-> privileged deterministic broker -> verification -> history

The model never receives the user's sudo password (authentication happens through sudo/polkit/PAM outside model context), and it has no code path to read private files: system access is not home-directory access.

Phoebus ships no model: the user connects a remote provider (DeepSeek/OpenAI) or downloads a local model, and a configured provider only ever receives approved, bounded system facts. A connected model is required to install, and it is the primary way to operate the system: when one is present, the assistant is used proactively. It is never required to boot, run or recover — the deterministic command line (sys, emerge, nix, flatpak) is always available as a break-glass fallback. Installation requires the network (stage3, Portage, packages); the installed system must not.

The assistant is the preferred front-end, never a gate. The deterministic command line is always available with no model, and a user who wants the old-fashioned way can always use it directly:

sys install vim                 # typed broker, offline parser, no LLM
sys enable sshd
sys history
emerge www-client/firefox       # Portage (the Gentoo `apt install` equivalent)
nix shell nixpkgs#nodejs        # Nix development environments
flatpak install flathub org.chromium.Chromium

Whatever the assistant can do, a human can do without it; the assistant only makes it easier.

Non-goals

  • A custom init system, package manager, audio stack or compositor.
  • A giant kernel fork or a large downstream patch set.
  • Bleeding-edge/experimental defaults.
  • Making a remote LLM/provider required to boot, run or recover. The local assistant must work offline, and deterministic tools remain available.
  • Rebuilding the world on a small release VPS.

Definition of a successful distribution

Phoebus installs a bootable, encrypted, systemd system in a disposable UEFI VM, boots with the installer media removed, unlocks LUKS, reaches a login and a functional Wayland desktop, and can be maintained without the user becoming a Gentoo expert. This is verified per docs/STATUS.md.