phoebus_os/docs/SYS.md
Phoebus 3435d5aed1
Some checks are pending
ci / test (push) Waiting to run
docs: record the VM-verified install journey
Record the disposable-VM evidence for the AI-first install workflow: the
deterministic install, the explicit --portage install/remove journey with a
protective snapshot and durable history, the no-model offer, the read-only
investigation actions, and the 19/19 acceptance matrix. Note the AI-selected
journey as the remaining gate (needs a connected provider).
2026-09-23 21:42:11 -07:00

12 KiB
Raw Blame History

sys — the deterministic Phoebus system interface

sys is the typed, validated execution boundary shared by the assistant and the offline (no-model) administrator. Whatever the assistant can do, a human can do by typing the same action; the assistant only makes it easier. The AI path emits the same closed action schema, and the LLM never holds privilege: every mutation is reviewed and authenticated by a human through the privileged broker.

sys <phrase>                 # deterministic parser (no model)
sys --action '<json>'        # one typed action
sys --action-file plan.json  # a typed action from a file
sys ask "<request>"          # assistant proposes the same typed actions

Run sys --help for the flags. Mutating actions require root (sudo sys ...). Without a model, sys ask prints the deterministic equivalent and exits.

AI-first installation (sys install)

sys install firefox                    # AI investigates and recommends
sys install firefox --flatpak          # deterministic, no model
sys install firefox --portage
sys install nodejs --nix
sys install thunderbird --snap
sys install MyTool --appimage
sys install app-misc/my-thing --ebuild # build a staged custom ebuild
sys ask install firefox                # the same workflow via the assistant

One shared workflow (ADR 0013) is used by all of these:

identify -> evidence -> AI investigation -> proposed selection
-> deterministic validation + effects -> review -> approve -> execute
-> verify -> history
  • Unqualified installation consults the connected model. The model may request bounded, read-only evidence (discover_candidates, inspect_candidate, check_backend, inspect_installation) and may ask one bounded question about your intent. It returns a structured proposal naming a real candidate id; the deterministic resolver independently confirms that candidate against backend metadata, computes the effects, and binds approval to a digest. A fabricated, stale, ambiguous or duplicating proposal is rejected and returned to the model for a bounded revision.
  • Explicit backend flags (--portage, --flatpak, --nix, --snap, --appimage, --ebuild) bypass the model, are mutually exclusive, and never fall back to another lane. If the lane cannot satisfy the request, the reason and alternatives are shown and nothing is installed.
  • No model for an unqualified install: the deterministic candidate selection and the explicit commands are printed, and nothing is installed. A provider failure is never permission to install through a lane.
  • Every install is recorded in the transaction log before it runs (an interrupted run leaves an in-progress record) and verified afterwards (package database, flatpak list, snap list, or the managed AppImage record). A verification failure is a failed transaction.

Read-only investigation is also directly available:

Phrase / JSON Typed action Kind
(JSON only) discover_candidates read
(JSON only) inspect_candidate read
(JSON only) check_backend read
(JSON only) inspect_installation read

Example:

sys --action '{"action":"discover_candidates","query":"firefox","gui":true}'
sys --action '{"action":"check_backend","backend":"snap"}'

Commands and typed actions

Services (Portage/systemd ownership)

Phrase Typed action Kind
inspect sshd inspect_service read
enable sshd enable_service mutate
disable sshd disable_service mutate
start sshd start_service mutate
stop sshd stop_service mutate
restart sshd restart_service mutate

Packages (Portage)

Phrase Typed action Kind
install vim / add vim install_package mutate
remove vim / uninstall vim remove_package mutate
search firefox / find firefox search_packages read
update update_system mutate
prepare updates prepare_updates mutate
what are you compiling inspect_updates read
(JSON only) inspect_package read

Source selection (all lanes)

Phrase Typed action Kind
choose firefox choose_package read
choose firefox via flatpak choose_package read
choose spotify as a gui sandboxed app choose_package read
prefer firefox via flatpak set_package_preference mutate
prefer firefox auto set_package_preference mutate

choose resolves real backend metadata, applies the shared policy (ADR 0006), and prints the selected lane, version, provenance, integrity, sandbox level, sizes, update behaviour and the rejected alternatives. It never installs anything and never fabricates a candidate.

Flatpak

Phrase Typed action Kind
flatpak install org.chromium.Chromium flatpak_install mutate
flatpak remove org.chromium.Chromium flatpak_remove mutate
flatpak list flatpak_list read

Nix (developer lane)

Phrase Typed action Kind
nix prepare nodejs python312 nix_prepare mutate

Snap (opt-in; app-containers/snapd through Portage)

Phrase Typed action Kind
snap find notes snap_find read
snap info thunderbird snap_info read
snap install thunderbird [channel] snap_install mutate
snap remove thunderbird snap_remove mutate
snap list snap_list read
snap refresh [name] snap_refresh mutate
snap connections thunderbird snap_connections read

Snap requires a ready snapd daemon. If it is absent, snap_install installs app-containers/snapd through Portage and enables snapd.socket first. Confinement is detected (strict/partial/none); --classic is only used when the typed action sets "classic": true and is shown in the review. The plan notes that snapd also refreshes automatically.

AppImage (opt-in; managed, not sandboxed)

Phrase Typed action Kind
appimage import /path/App.AppImage appimage_import mutate
(JSON only) appimage_acquire mutate
(JSON only) appimage_update mutate
appimage remove name appimage_remove mutate
appimage info name appimage_info read
appimage list appimage_list read

Acquisition requires a pinned SHA-256; a placeholder or mismatch is refused and the download is discarded. Architecture is read from the ELF header without executing the image. Desktop entries are installed, and user data is preserved on removal unless "purge_data": true. AppImage provides no application sandbox and is described as such.

Custom ebuilds (Phoebus overlay)

Phrase Typed action Kind
ebuilds / custom ebuilds custom_ebuild_list read
(JSON only) custom_ebuild_prepare mutate
(JSON only) custom_ebuild_install mutate
(JSON only) custom_ebuild_remove mutate

A custom ebuild is untrusted executable code. custom_ebuild_prepare writes it to /var/db/repos/phoebus with a rationale and the SHA-256 of its exact content; it does not build it. custom_ebuild_install requires that same digest, regenerates the Manifest and builds through Portage with its sandbox enabled. Editing the staged ebuild invalidates the approval.

Snapshots and rollback

Phrase Typed action Kind
snapshot before update create_snapshot mutate
undo / rollback undo mutate
undo status rollback_status read
history history read

Acceptance matrix

The matrix below is the repeatable acceptance suite. installer/tests/vm/ sys-acceptance.sh runs the deterministic and JSON groups inside a booted, installed, detached VM and prints a machine-readable summary; it is safe to run with no network and no model.

# Case Command Expected
1 Identity sys --version prints the version, exit 0
2 Read-only history sys history state, exit 0, no mutation
3 Invalid natural operand sys -- install --color=n rejected, nonzero
4 Unknown phrase sys frobnicate rejected, nonzero, examples shown
5 JSON unknown action --action '{"action":"run_shell"}' fail closed, nonzero
6 JSON unknown field --action '{"action":"history","x":1}' fail closed, nonzero
7 Option-like operand (JSON) install_package atom="-C" rejected before any command
8 Invalid Snap name snap_install name="Bad Name" rejected, nonzero
9 Invalid AppImage hash appimage_acquire sha256="00" rejected, nonzero
10 Ebuild path traversal custom_ebuild_prepare atom="../../x" rejected, nonzero
11 Choose with no lane sys choose unused-name selection or clear failure, never invented
12 Inventory (empty root) --root T appimage list / ebuilds "no managed …", exit 0
13 Mutating as non-root set_package_preference refused: needs root
14 Snap daemon absent snap list on a system without snapd useful error, nonzero
15 Install a tiny package sys install app-misc/hello (Portage) installed; emerge -p confirms; recorded in sys history
16 Remove it sys remove app-misc/hello removed; recorded
17 Service lifecycle sys enable/start/stop sshd unit state matches systemctl
18 Update preparation sys prepare updates then what are you compiling state reported truthfully
19 Snapshot + undo sys snapshot, mutate, sys undo, reboot root/var/package state restored
20 Approval rejected answer n at the prompt no mutation, nonzero
21 Plan changed between review and exec concurrent metadata change aborts, nonzero
22 Offline sys ask sys ask "<request>" with no provider deterministic fallback, nonzero
23 Unqualified install consults the model sys install firefox with a provider model investigated; resolver confirmed
24 Explicit backend, no model sys install firefox --flatpak with no provider deterministic, no model consulted
25 Conflicting backend flags sys install x --flatpak --nix rejected by the CLI
26 Explicit lane cannot satisfy sys install x --portage without Portage explained, no fallback, nonzero
27 Unqualified with no model sys install firefox and no provider deterministic offer printed, nothing installed
28 Ambiguous friendly name a name matching several candidates clarification required, nonzero
29 Fabricated candidate model proposes a non-existent id rejected, revised, no install
30 Changed candidate version metadata changes after review approval invalidated, nonzero
31 Failed install history a failing backend command transaction recorded as failed

Cases 1–14 and 21–31 are covered by host tests (crates/phoebus-core/src/selection.rs, .../action.rs, crates/phoebus-ai/src/install.rs, crates/phoebus-executor/src/{install,snap,appimage,ebuild,chooser,transaction}.rs, and crates/phoebus-installer/tests/sys_cli.rs). Cases 15–20 and the in-VM subset are exercised by the VM acceptance script; their current verification status is recorded in docs/STATUS.md.

Verified in the disposable VM (deterministic minimal install, booted detached): sys install app-misc/hello --portage (plan + effects → snapshot → install → package-database verification → durable history), sys remove app-misc/hello, the no-model offer and flag-conflict cases, and the read-only investigation actions; sys-acceptance.sh reported FAIL=0 (19/19). The AI-selected journey needs a connected model and is the remaining gate (docs/HANDOFF.md).

Security properties

  • No shell. Every command is an argument vector through phoebus-executor::Exec; there is no sh -c on any path.
  • Validated at the boundary. Every action (manual, JSON, or AI) is re-validated before a command is built; option-like operands are rejected.
  • Target-root isolation. Alternate-root operations are chrooted; runtime operations (services, Snap) refuse an alternate root.
  • Approval binding. A resolved plan has a digest; a material change between review and execution aborts. A custom ebuild binds approval to its content digest.
  • Secrets travel only through mode-0600 files/stdin and are redacted from logs and history.