Appliance feature parity: everything host-CLI-only is impossible on a shell-less box

[VijitSingh97]

The finding

The control gate's design is correct and must not be weakened: wallets, view keys, auth,
onion exposure, tokens, per-rig descriptors and the security perimeter are deliberately
host-CLI-only — the dashboard container must never be able to commit them, because a
compromised container could then swap a payout wallet or exfiltrate a view key.

But the design's escape hatch is "edit config.json on the host and run ./pithead apply" —
and the appliance HAS no host access: no shell, SSH disabled. Every host-only item is
therefore not "inconvenient" on the appliance, it is impossible after first boot. The
wizard covers most of them at setup; changing them later means a reinstall.

What an appliance operator cannot do today

Lost capability	DIY path	Severity
Change the payout wallet	edit + apply	The most important operator action over a machine's life
Enable/change payout confirmation (view keys, scan heights)	edit + apply	Flagship feature, post-setup
Add/edit a rig in workers.list (per-rig control/upgrade)	edit + apply	Fleet management
Change the dashboard password, enable the onion	edit + apply	Security lifecycle
Add/change Telegram or Healthchecks after setup	edit + apply	Alerting lifecycle
Switch node mode local↔remote, change remote hosts	edit + apply	Topology changes
Encrypted backup / restore (wallet settings, Tor keys, config)	pithead backup/restore	Disaster recovery — currently NOTHING exports state off an appliance
Support bundle, doctor detail, secrets rotation	CLI	Supportability

The designed answer, and the appliance-native one

The gate's own comments name the plan: #338 out-of-band approval (Telegram approve/deny
with deny-on-timeout) drops in where the refusal happens today, turning perimeter changes
into dashboard-initiated + second-factor-approved. That is the right general mechanism.

An appliance-native complement worth designing alongside it: physical presence as the
second factor — the machine already reads pithead-config.json from a FAT partition at
first boot; extending that to "a config on inserted removable media, confirmed on the
console, applies on any boot" gives holders-of-the-hardware a host-equivalent channel with
no network trust at all. That is what host-CLI-only actually means operationally: someone
with hands on the machine.

Backup/restore needs its own dashboard surface regardless (download an encrypted
backup.tar.zst; restore at wizard time from an uploaded one — the restore half naturally
belongs to the wizard's pre-seed path).

Sequencing

Pre-GA blockers, in order of user pain: (1) backup export, (2) #338 or the physical-presence
channel for wallet/keys/workers changes, (3) restore-at-setup. The dashboard OS-update
action is tracked separately and compounds with (2).

[VijitSingh97]

Decomposition proposal. Everything below is derived from the code on develop (the gate: pithead ~L5315–5500) and feat/phase2-bakery-image (the wizard, os/, docs/appliance.md) — not from this issue's table. Corrections to the table are called out first, then the sub-issues.

1. The host-only set as the code defines it today

The commit gate (control_approval_gate) allows exactly two key sets and refuses everything else, fail-closed:

Already dashboard-committable — not lost on the appliance:

• Free set (CONTROL_DASHBOARD_EDITABLE_KEYS): p2pool flags/port, xvb.enabled + xvb.donation_level, dashboard.tari_required / fail_closed / check_for_updates / timezone, mem limits, prep threads, hashrate-drop thresholds, the daily-summary time, and all ~26 telegram.events.* toggles.
• Confirm-gated set (CONTROL_DASHBOARD_CONFIRM_KEYS, Config editability: confirm-gate the operationally-disruptive fields (keep the perimeter host-only) #719): the four data-dir moves, p2pool.stratum_port, monero.clearnet_initial_sync / tari.clearnet_initial_sync, prune enable.
• dashboard.energy.* (config.json-only, explicitly allowed).

Refused today — the actual appliance gap, grouped:

Class	Config paths
Wallets	monero.wallet_address, tari.wallet_address
Payout confirmation	monero.view_key + payout_scan_height; tari.view_key + spend_public_key + payout_scan_birthday
Fleet	workers.list[] / dashboard.workers[] (refused as a block, per-rig hosts+tokens), workers.api_port / api_auth / api_token
Security perimeter	dashboard.auth.*, dashboard.onion.*, dashboard.control.enabled, network.tor_egress_firewall, p2pool.stratum_password / stratum_tls / stratum_bind, ssh.enabled / ssh.authorized_key
Topology & identity	monero.mode / tari.mode (DEST-refused), *.remote.*, monero.node_username / node_password, xvb.url / donor_id / tor, network.subnet, dashboard.host / port / secure, the LAN-access toggles, local_miner.enabled (ties to #796)
Alerting identities	telegram.enabled / bot_token / chat_id, telegram.commands.* / telegram.control.*, healthchecks.ping_url, notifications.webhooks / ntfy.* / tor
Tamper evidence	telegram.events.wallet_changed, telegram.events.clearnet_exposed — excluded from the allowlist on purpose: they are the alarms on the very channel an approval flow would ride

Plus the non-config CLI operations: backup / restore, rotate-secrets, rotate-dashboard-onion, onion-client-key, doctor, reset-dashboard, logs.

Corrections to this issue's table:

1. "Add/change Telegram after setup" — overstated. Every event toggle and the summary time are already dashboard-editable; what is host-only is the channel identity (enabled, bot_token, chat_id) and the commands/control blocks. Healthchecks (ping_url) is host-only as stated, and notifications.* (webhooks, ntfy) belongs on the list too.
2. "Support bundle" — no such CLI command exists on develop. Nothing to lose; if one is wanted it is a new feature, not parity.
3. Not lost at all: data-dir moves, stratum-port repoint, clearnet-sync enable, prune enable — all confirm-gated dashboard commits since Config editability: confirm-gate the operationally-disruptive fields (keep the perimeter host-only) #719.
4. "Impossible after first boot" holds for remote/headless operation, which is the product. But strictly: the appliance sets a root console login to the dashboard password every boot (provision_console_login, bakery branch), and /data/pithead holds the full CLI on a writable partition — so someone at the machine with a keyboard has a raw escape hatch today. It is a root shell, not a designed surface, and docs/appliance.md deliberately doesn't present it as one. Same for key-only SSH when enabled at setup.
5. #338 is closed and shipped (v1.5): per-action Telegram confirmation with deny-on-timeout, per-operator rate limit, telegram.control.allowed_ids / confirm_timeout — but only for the fixed verbs /restart and /apply-current-config. The gate's comment names Telegram two-way control commands (restart / apply) with access control #338 as the drop-in design; the actual gate extension is unbuilt, so it needs a new issue (sub-issue C below), not a reopen.

2. Proposed sub-issues

A. Backup export from the dashboard. New fixed control verb backup on the #33 host runner, next to restart/apply/upgrade: host-side runs the existing stack_backup machinery, encrypted only (refuse a passphrase-less request outright — the CLI's --no-encrypt stays CLI-only), archive lands in a mount the container can serve for download. Mechanism: dashboard surface over the existing spool; no gate change. Coverage: tier 1 for the verb/refusal logic (tests/stack + pytest, like the existing verbs), one tier-4 release-checklist item for the real download. Depends on: nothing. The archive format already exists (pithead-backup-*.tar.gz.enc, #374).

B. Restore at setup. The wizard accepts an uploaded encrypted backup + passphrase as an alternative to the config form; host side decrypts and extracts onto /data before provisioning, riding the existing firstboot spool ("container asks, host decides") and the pre-seed contract (a rejected archive falls back to the normal form, never blocks). Mechanism: wizard/pre-seed extension on the bakery branch. Coverage: tier 1 for stage/spool logic (test_wizard.py pattern), the KVM install gate for the boot leg. Depends on: A's format only — which already exists, so B is buildable independently; A+B together close the disaster-recovery loop.

C. Out-of-band approval at the commit gate. The gate's two refusal classes (non-allowlisted key, DEST row) become a pending approval instead of a flat refusal: prompt shows the exact porcelain diff ("change payout wallet to 4A…xyz — approve?"), deny-on-timeout, per-operator rate limit — the #338 semantics, reusing its shipped config surface (telegram.control.*). Two hard constraints from the existing design: (1) the host must verify the approval — the shipped ControlGate lives in the dashboard container and is documented as UX, not the boundary; a wallet swap cannot trust a container-relayed "approved". The host runner holds the bot token via config.json, so it can drive its own confirm exchange; the mechanism is the core design work of this issue. (2) A never-approve set stays refused even with approval: the tamper-evidence toggles, telegram.bot_token/chat_id/control.* (channel identity — approving a channel swap over the channel is takeover), dashboard.control.enabled, ssh.* (docs/appliance.md commits "neither can be changed from the dashboard later"), and the #728 data-dir destination rule. Config editor surfaces the new class as _approval_keys, same pattern as _editable_keys/_confirm_keys. Coverage: tier 1 heavy (the gate is pure shell, the prompt logic pure Python), tier 4 for one live Telegram round-trip. Depends on: nothing in code; operationally requires Telegram already configured — a box without it can never bootstrap Telegram through this channel, which is exactly what D covers.

D. Physical-presence channel: removable media on any boot. Extend the pre-seed path from first-boot-only to every boot: pithead-boot (or a udev-triggered unit) finds pithead-config.json on inserted FAT media, validates it with the existing pre-seed machinery, shows the diff on the console, and applies only after a console confirmation; deny-on-timeout or on removal. Same trust statement as host-CLI-only today: hands on the machine. Covers everything, including C's never-approve set, and is the recovery path when Telegram was never configured or its token is lost. Mechanism: appliance-only (os/ + pithead-boot), no gate or dashboard change. Coverage: tier 1 for diff/accept/reject logic, KVM gate for the boot-with-media leg. Depends on: nothing.

E. Fleet editing behind the approval channel. Lift the categorical workers.list[] refusal into a C-style approval: add/edit/remove a rig from the Workers view, prompt shows the per-rig host delta. Kept separate from C because it is a different refusal mechanism (config.json-only block, not the env allowlist) and a different UI surface. Coverage: tier 1 (gate + worker view), tier 3 mini-stack for the end-to-end edit. Depends on: C.

F. CLI-parity remainder (post-GA). doctor output surfaced or downloadable from the dashboard; rotate-secrets / rotate-dashboard-onion as approval-gated actions; onion-client-key retrieval. Grouped because each is small and none blocks GA. Depends on: C.

3. Recommended order

A → B → D → C → E → F, with A+B+D as the pre-GA bar.

Reasoning: A first because it is the only irreversible loss today — a dead appliance takes wallet settings, Tor identities and the dashboard DB with it, and nothing exports state at all. B second: it completes the recovery loop and rides paths that already exist on the bakery branch. D before C, deliberately reversing this issue's "(2) #338 or physical presence" coin-flip: D restores full parity (including the never-approve set and the no-Telegram bootstrap case) with no new trust decision — holder-of-the-hardware is what host-CLI-only already means — while C introduces the one genuinely hard new design (host-verified remote approval for wallet-grade changes) and covers only its approvable subset. Ship the trust-conservative, complete channel first; C then adds remote convenience rather than being the load-bearing parity answer. E and F ride C. The dashboard OS-update action stays where it is tracked (#77 phases / #394) and compounds with C.

4. Open questions (operator)

1. Pre-GA bar: is A+B+D the GA gate, with C/E as fast-follows — or do you consider remote (no-hands) wallet changes a GA requirement, which pulls C forward?
2. Never-approve set membership: confirm the list in C — in particular whether ssh.enabled stays physical-presence-only (the docs currently promise it), and whether dashboard.auth.password is approvable via C or belongs with D only.
3. Console escape hatch: the root console login exists on the bakery branch. Document it as a supported break-glass path (which weakens the "shell-less" story but is honest), or keep it undocumented and let D be the only sanctioned physical channel?
4. Backup passphrase UX in A: typed per export in the browser (never stored), or a standing passphrase in config.json? Typed-per-export is the safer default; confirm.
5. DEST rows in C: should approval also cover DEST-flagged changes (node-mode switch is the table's headline case), or is v1 limited to non-allowlisted keys with DEST staying refused? The sub-issue scope changes materially.
6. D's confirm surface: console keypress only, or is media-insert + reboot with a console countdown acceptable for boxes with no keyboard attached? Affects whether D needs any input handling at all.

If this breakdown holds, I'll file A–F as issues with these scopes and cross-link them here.

🤖 Generated with Claude Code