main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-setup description: >- Hydrogen's setup panel on Linux: the install-step cascade, Run All, Rollback All, Virgin Reset with its toggles, keeping auth during resets, and test patterns. Read before running setup or a virgin reset. Use when asked about the setup panel, run all, a failed step, the password prompt during setup, or reset workspace.

Hydrogen -- Setup Panel & Virgin Reset

Zero-Click Goal

Setup targets zero manual clicks. The golden workspace image already carries code-server, the Adom CLIs, the claude CLI and Code extension, VS Code settings and the hydrogen-* skills. Setup builds the workspace machine from that image, binds your Adom session, checks the relay and opens Welcome. Never tell the user to install something by hand. See hydrogen-golden-image.

The one thing a Linux user may see: a single desktop password prompt (pkexec) on the first run of an AppImage, or for a user outside the sudo/wheel/admin groups. It installs systemd-container if missing, the root helper /usr/libexec/adom-hydrogen/hydrogen-workspace and a sudoers rule for that one file. The .deb and .rpm packages install these themselves, so no prompt appears. While the prompt is up, the step log says it is waiting for the password every 20 s.

The Install Steps

Halt-on-failure, resume-not-restart, per-step 3x auto-retry. State is per step (pending / running / done / failed, output, percent) in ~/.config/hydrogen-desktop/setup-steps-workspace.json; Hydrogen reads it at launch to decide whether the setup panel opens. The step list and what each step does are in hydrogen-setup-steps.

Panel Buttons

  • Run All — executes all pending steps sequentially. STOPS on first failure.
  • Rollback All — rolls back all completed steps in reverse order.
  • Virgin Reset ▾ — opens the toggle panel (see below).
  • Run (per-step) — runs a single step.
  • Rollback (per-step) — rolls back a single step.

CRITICAL: Run All Stops on Failure

If any step fails, Run All ABORTS (halt-on-failure, after the per-step 3x auto-retry is exhausted). Remaining steps are NOT executed. The cascade resumes — it does NOT restart from the first step — so to recover after a failure: fix the issue, then either:

  • Click "Run All" again (it resumes from the first not-done step)
  • Click "Run" on the failed step to retry just that one

Virgin Reset Toggle Panel

Click "Virgin Reset ▾" to expand the wipe options. Each toggle has a live status badge showing the current state. The ONLY programmatic trigger is POST /setup/panel/run-virgin-reset (see below).

Toggle (option key) What it wipes Status badges
Install step state (install_state) Resets all steps to pending CLEAN / EXISTS
Workspace (container) PRISTINE wipe + re-provision of the workspace (ONLY Hydrogen's own workspace) GONE / RUNNING / EXISTS
Image tarball (tarball, legacy image) Deletes the cached golden image (full re-download) CACHED / GONE
Webview storage (webview_storage) Queued wipe, flushed at next Hydrogen launch (restart_required) CLEAN / EXISTS
VS Code state (vscode_state) Queued wipe, flushed at next Hydrogen launch (restart_required) CLEAN / EXISTS
Adom session token (adom_token) Deletes hydrogen-session.txt CLEAN / EXISTS
Claude credentials (claude_token) Deletes the host-side Claude creds backup CLEAN / EXISTS

On Linux the container toggle removes the Adom-Workspace machine and every file in it, including /home/adom/project; the next setup imports a fresh one. tarball deletes ~/.local/share/Adom/HydrogenDesktop/cache/adom-golden.tar.gz (forces the full image download), and adom_token also deletes the session's replay copy and forces sign-in.

confirmed_destructive must be set for the reset to proceed. "Wipe Selected" at the bottom executes the reset for all checked toggles.

The workspace reset is a PRISTINE wipe + re-provision — it backs up Claude creds first UNLESS claude_token is checked. The webview_storage / vscode_state wipes are queued and flushed at the next Hydrogen launch (restart_required), NOT immediate; there is no reboot for the wipe.

CRITICAL: the virgin reset only ever touches Adom-Workspace: the helper refuses any other machine name and its shutdown stops only that machine, never the user's other containers.

Automated Testing Pattern

For AI-driven ralph loop testing, keep auth tokens so steps don't fail:

Checked:   install_state, container
Unchecked: tarball (cached, saves the full-image re-download),
           adom_token, claude_token

Programmatic triggers (the ONLY supported headless paths)

CTL=$(cat ~/.adom/hydrogen-control-url)
# Virgin reset: the ONE allowed programmatic trigger. It shows the panel and the
# checkboxes, pauses, then runs. Defaults are the keep-auth set; override in "options".
curl -X POST $CTL/setup/panel/run-virgin-reset -H Content-Type:application/json \
  -d '{"options":{"tarball":false,"adom_token":false,"claude_token":false}}'

# Re-run one step (continue_after keeps going)
curl -X POST $CTL/setup/step/test-relay -H Content-Type:application/json -d '{"continue_after":true}'

Refused (deprecated headless triggers): POST /setup/virgin-reset, POST /virgin-reset, POST /setup/run-all, POST /setup/run-step, and the old workspace-unregister route. Use the two above.

When a step fails

The card names a Linux fix when it knows one:

  • helper, systemd-container, pkexec or sudo -n errors: reinstall the Hydrogen package (.deb or .rpm) or approve the permission prompt, then Retry.
  • the workspace could not be built: in a terminal run sudo machinectl terminate Adom-Workspace; sudo machinectl remove Adom-Workspace (clears a half-built copy), then Retry.
  • the workspace did not finish starting: sudo machinectl terminate Adom-Workspace, then Retry.

Setup never asks for a computer restart on Linux. The full reason is in ~/.config/hydrogen-desktop/hydrogen-desktop.log.

  • hydrogen-setup-steps: each step and what it did
  • hydrogen-golden-image: what the image carries
  • hydrogen-workspace-lifecycle: start, stop, import, remove mechanics