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).
12 KiB
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 nosh -con 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.