Some checks are pending
ci / test (push) Waiting to run
The no-model fallback is the Phoebus deterministic CLI (sys) running the same typed actions the assistant emits, exposed as an explicit non-AI (legacy) mode. Raw emerge/nix/flatpak remain a last resort rather than the intended front-end.
108 lines
5 KiB
Markdown
108 lines
5 KiB
Markdown
# 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. There is **one control plane**: the
|
|
typed actions the assistant emits are the same ones the Phoebus CLI (`sys`)
|
|
executes. That CLI — not raw Portage — always works without a model, 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 **Phoebus deterministic CLI** (`sys`) runs the same typed
|
|
actions the assistant emits, with no model, as an explicit non-AI ("legacy")
|
|
mode. Raw `emerge`, `nix` and `flatpak` remain but are a last resort, not the
|
|
intended front-end. 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`.
|