# `sys` — the Phoebus system interface `sys` is the typed, validated execution boundary shared by the desktop assistant (`phoebus-assistant`) and the offline/deterministic 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. ```sh sys # natural language / AI workflow (default) sys please # natural conversational alias (same AI workflow) sys ask "" # assistant proposes the same typed actions sys --legacy # explicit deterministic mode (no model interaction) sys --legacy --action '' # one typed action in deterministic legacy mode sys --broker --action '' # internal broker invocation for shared UI / bridge sys --assistant-bridge # stdio JSON-RPC bridge for the desktop assistant ``` Run `sys --help` for the full list of flags. Mutating actions require root (`sudo sys ...`). Without a model, AI workflows stop and print the actionable deterministic legacy alternative (`sys install --legacy --`) instead of silently falling back or switching sources. > [!NOTE] > `--legacy` is the administrative flag for `sys` deterministic operations. > `--no-ai` is an installer-only break-glass flag reserved exclusively for > non-interactive ISO installations (`installer-rs/tests/ai_guidance.rs`). ## AI-first installation (`sys install`) Natural language is the default interaction. Source flags alone constrain the AI investigation to a specific package source without bypassing the model: ```sh sys install firefox # AI investigates and recommends a package source sys please install firefox # identical AI workflow sys ask "install firefox" # identical AI workflow sys install firefox --flatpak # AI workflow constrained to Flatpak sys install firefox --portage # AI workflow constrained to Portage sys install nodejs --nix # AI workflow constrained to Nix sys install thunderbird --snap # AI workflow constrained to Snap sys install MyTool --appimage # AI workflow constrained to AppImage sys install app-misc/my-thing --ebuild # AI workflow constrained to custom ebuild ``` Removal is also AI-first by default. The deterministic ownership discovery and policy validation always run underneath; the connected model confirms the exact discovered copy. An ambiguous multi-lane install still requires an explicit source flag, and a model failure stops execution rather than silently removing deterministically: ```sh sys remove firefox # AI workflow: confirm target, then remove sys remove firefox --flatpak # AI workflow constrained to Flatpak sys remove firefox --legacy # deterministic removal, no model sys remove firefox --legacy --flatpak # deterministic removal from Flatpak ``` ### Deterministic administration (`--legacy`) Deterministic operation must be explicitly selected with `--legacy`: ```sh sys install firefox --legacy --flatpak # deterministic Flatpak workflow; no model interaction sys install firefox --legacy --portage # deterministic Portage workflow; no model interaction sys remove firefox --legacy # deterministic removal, no model interaction sys history --legacy # deterministic history without model sys undo --legacy # deterministic recovery without model sys install firefox --legacy # REFUSED: requires an explicit package source flag ``` When `--legacy` is used with `install` but without an explicit source flag, execution is refused and available package sources are displayed. `--legacy` never contacts a model. Direct JSON and action-file invocations (`--action` and `--action-file`) are audited entry points: they fail closed unless invoked with `--legacy` (for deterministic administrator usage) or `--broker` (for internal UI/bridge calls). One shared workflow (ADR 0013) is used by all installations: ``` 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. - **Source flags without `--legacy`** constrain the AI investigation to the specified backend, ensuring the model evaluates and explains candidates for that source while preserving the full investigation, explanation, and approval cycle. - **Explicit backend flags with `--legacy`** bypass the model entirely, 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 / Provider failure**: For an unqualified install without a model or upon provider error, the operation halts cleanly. The deterministic candidate selection and explicit `--legacy` commands are printed, and nothing is installed. A provider failure is never permission to install through a lane silently. - 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. User data is preserved by default on removal. 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: ```sh 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 (personal) | | `prefer firefox auto` | `set_package_preference` | mutate (personal) | | *(JSON only)* `system_wide: true` | `set_package_preference` | mutate (privileged) | `prefer ...` saves the invoking user's own preference; it needs no elevation and is stored under the user's config directory. The system-wide default is the same action with `"system_wide": true`, which requires the authenticated broker. At resolution time the personal choice wins and system defaults fill anything the user has not set. `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 | ## Desktop assistant bridge (`sys --assistant-bridge`) The desktop assistant GUI (`phoebus-assistant`) is a lightweight Quickshell QML interface that delegates all logic to `sys --assistant-bridge`. The bridge runs a stdio JSON-RPC server speaking newline-delimited JSON messages: - `handshake`: validates client identity and checks active AI model connectivity. - `ask`: submits a conversational request (`install firefox`, `why is audio broken?`) into the shared AI workflow, returning a reviewed plan card for install, removal, general administration, or a follow-up confirmation. Every plan type carries the same `plan_id`/`digest` review and approval state; information and clarification replies carry no execution control. Removal is AI-first by default. - `execute`: executes exactly the referenced reviewed plan by plan ID and plan digest. The privileged broker repeats the full validation. - `legacy_install`: performs deterministic installation with an explicit backend. - `legacy_execute`: executes typed actions deterministically. - `clear_conversation`: deletes the persisted, minimized follow-up context. - `updates`: queries the unified multi-source update system across Portage, Flatpak, Snap, AppImage, and Nix. - `proactive_alerts`, `proactive_snooze`, `proactive_dismiss`: interacts with the quiet proactive system monitor. - `get_preferences`, `set_preferences`: inspects and edits the invoking user's package source profiles, project environment tool mappings, and keep-existing-source pins. Personal preferences are stored 0600/0700 under the user's own config (`~/.config/phoebus/package-preferences.toml`) without elevation; system defaults stay root-owned. A failed write is reported as an error, never as "saved". - `history`, `undo`: queries transaction logs and initiates recovery. Zero business logic lives in the GUI: equivalent CLI and GUI requests produce identical validated plans given the same facts and preferences. ## Privileged execution boundary A mutating plan is stored as a `PreparedPlan` in per-user storage (`/run/user//phoebus/plans`, mode 0700; a 0600 plan file; atomic write; a 128-bit unpredictable identifier). The plan is sealed with an integrity digest over the reviewed fields, the target root and the initiating uid. That seal is the **approval fingerprint**: it covers the exact actions, per-step effects, candidate, target root, initiating uid and expiry. `execute_plan` validates the plan before elevation and again — authoritatively — inside the privileged broker (`sys --broker --execute-plan --plan-uid --approval-digest --root `). The broker: - carries the digest the review card showed the user across authentication independently of the plan file, and refuses a plan whose recomputed digest does not match it — so a replacement plan under the same identifier is rejected even when it is resealed with a valid, self-consistent checksum; - re-derives the integrity seal from the plan's own contents (it never trusts two supplied digest strings); - rejects expired, modified, malformed, wrong-root or wrong-uid plans; - derives the initiating identity from the authenticated caller context (`PKEXEC_UID`), treating `--plan-uid` as untrusted input; - revalidates the current package/removal state after authentication, and again action-by-action at the execution boundary against the reviewed effects; - anchors consumption in a **root-owned approval ledger** (`/var/lib/phoebus/approvals`, 0700 / 0600, ADR 0014). The fingerprint is claimed with `O_EXCL`, so at most one execution may run under concurrent submissions, and a retry is refused even after the user deletes every file in their own plan directory. A plan left `in_progress` by a crash is reconciled to `interrupted` at broker startup; a consumed approval is retained. - treats the plan file and its contents as untrusted input, resolving storage from the uid rather than an arbitrary path. Authentication happens outside model context through Polkit (`pkexec`), never passwordless sudo. Cancelling or refusing authentication performs no mutation and consumes nothing: authentication precedes the ledger claim. A failed, stale-plan, verification-failed or interrupted operation reaches a truthful terminal status. Each transaction records the outcome per action (`completed`, `failed`, `unattempted`) plus the protective snapshot, so a partial execution is visible and never reported as success. ## Transaction truthfulness Every mutation is recorded as an in-progress transaction **before** it runs. On action failure, verification failure, refusal or cancellation the same record is finished with a truthful result (`failed: …` / `verify failed: …`); completed steps and their protective snapshot are retained. A record that never reaches a terminal result is an interrupted operation, and its consumed plan cannot be replayed. A malformed broker reply is a protocol failure, never fabricated success. History persistence failures are surfaced, not swallowed. ## Conversation privacy Follow-up context is minimized before persistence: the raw request is never stored, only structured context (kind, application, candidate, rationale), and registered secrets are scrubbed with the active redactor. The history file is 0600 inside a 0700 directory, written atomically, bounded to ten turns, and can be cleared (`clear_conversation`) so it no longer informs later follow-ups. Redaction removes known secrets; it does not claim to detect arbitrary sensitive text, which is why raw requests are not persisted. ## Acceptance matrix The matrix below is the repeatable acceptance suite. `installer/tests/vm/sys-acceptance.sh` runs the deterministic, legacy, and JSON acceptance cases 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 (legacy) | `sys history --legacy` | state, exit 0, no mutation | | 3 | Undo status (legacy) | `sys undo status --legacy` | idle rollback state, exit 0 | | 4 | Non-root undo | `sys undo --legacy` (non-root) | requires root, exit nonzero | | 5 | AppImage inventory (empty) | `sys --legacy appimage list` | "no managed AppImages", exit 0 | | 6 | Ebuild inventory (empty) | `sys --legacy ebuilds` | "no custom ebuilds", exit 0 | | 7 | Invalid natural operand | `sys --legacy -- install --color=n` | rejected, nonzero | | 8 | Unknown phrase | `sys --legacy frobnicate` | rejected, nonzero, examples shown | | 9 | Audited action without legacy/broker | `sys --action '{"action":"history"}'` | fail closed, requires `--legacy` or `--broker` | | 10 | Legacy install without source | `sys install firefox --legacy` | refused: requires explicit source flag | | 11 | JSON unknown action | `--legacy --action '{"action":"run_shell"}'` | fail closed, nonzero | | 12 | JSON unknown field | `--legacy --action '{"action":"history","x":1}'` | fail closed, nonzero | | 13 | Option-like operand (JSON) | `install_package atom="-C"` | rejected before any command | | 14 | Invalid Snap name | `snap_install name="Bad Name"` | rejected, nonzero | | 15 | Invalid AppImage hash | `appimage_acquire sha256="00"` | rejected, nonzero | | 16 | Ebuild path traversal | `custom_ebuild_prepare atom="../../x"` | rejected, nonzero | | 17 | System-wide policy as non-root | `set_package_preference system_wide:true` | refused: needs root | | 17b | Personal preference as non-root | `set_package_preference` | saved to user config, no `/etc` write | | 18 | Offline `sys ask` | `sys ask ""` with no provider | deterministic fallback, nonzero | | 19 | Choose with no lane | `sys --root / choose unused-xyz --legacy` | selection or clear failure, never invented | | 20 | Conflicting backend flags | `sys install x --flatpak --nix` | rejected by CLI | | 21 | Source flag without install | `sys --flatpak history --legacy` | rejected by CLI | | 22 | Unqualified with no model | `sys install firefox` (no provider) | deterministic offer printed, nothing installed | | 23 | Read-only investigation | `--legacy --action '{"action":"check_backend",...}'` | structured JSON evidence returned | ### Mutating acceptance cases (disposable VM only) When `SYS_ACCEPTANCE_MUTATE=1` is set in the disposable VM: - `mutate-install`: `sys -y install app-misc/hello --legacy --portage` installs and verifies via `emerge -p`. - `mutate-remove`: `sys -y remove app-misc/hello --legacy` uninstalls cleanly. - `mutate-history`: `sys history --legacy` confirms both install and remove are logged. The read-only and failure acceptance cases (24, including the personal-preference case) are exercised by the test suite (`installer/tests/vm/sys-acceptance.sh`); the broker approval/replay regression is covered by `phoebus-installer` unit tests. Host unit and integration tests in `crates/phoebus-installer/tests/sys_cli.rs`, `crates/phoebus-core/`, and `crates/phoebus-executor/` cover proposal validation, digest matching, lane policy, and cross-source removal. ## 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.