phoebus_os/docs/OBJECTIVES.md
Phoebus ab7408cdcf docs: make AI and Nix defining, offline-capable subsystems
AI and Nix are now always-present parts of Phoebus (not optional add-ons):
the assistant ships with a local model so it works offline and in recovery,
and Nix is a second package lane shipped and updated through Portage.
Installation needs the network; the installed system must boot, run and
recover without it. The assistant is the preferred front-end, never a gate:
the deterministic CLI (sys, emerge, nix, flatpak) is always available. The
model still never holds privilege. Records ADR 0006 (package lanes).
2026-09-20 14:27:02 -07:00

4.2 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, built in. The assistant and Nix are defining, always-present subsystems, not optional add-ons. The assistant ships with a local model so it works offline; remote providers are an optional upgrade. A Phoebus system must boot, run and recover without the network.
  • 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.

The default brain is a local model, so the assistant works without a network and inside recovery. Remote providers (DeepSeek/OpenAI) are optional and only ever receive approved, bounded system facts. 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.