main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-setup-steps description: >- What Hydrogen's setup steps did to prepare the Linux workspace: build the systemd-nspawn machine from the golden image, bind the Adom session, check the relay, open Welcome. Use when asked what did setup do, why is X installed, re-run a setup step, why did step N fail, why did it ask for my password, or what a virgin reset is.

Hydrogen Setup Steps (Linux): what was done to prepare your workspace

On first launch (or after a virgin reset) Hydrogen turns this Linux computer into an Adom workspace: the Adom-Workspace systemd-nspawn machine, running on the host kernel (no VM). The tooling (code-server, the Adom CLIs, the claude CLI and Code extension, VS Code settings, the hydrogen-* skills) is baked into the golden image; setup builds the machine from it, binds your Adom session and opens Welcome. See hydrogen-golden-image.

The cascade lives in src-tauri/crates/hydrogen-setup/ (the same code as on the other platforms; Linux differs only at the runtime seam). Halt-on-failure, resume-not-restart, per-step 3x auto-retry. Work inside the machine runs as adom (home /home/adom) through the root helper sudo -n /usr/libexec/adom-hydrogen/hydrogen-workspace -d Adom-Workspace -u adom -- <cmd>. From inside the workspace you are already there: run commands directly.

The steps (in order)

# Step What it does on Linux
1 ensure-workspace Makes the host ready (systemd-container, the helper, its sudoers rule: one pkexec password prompt only if the package did not install them), downloads the pinned golden image (about 775 MB, cached), unpacks it into /var/lib/machines/Adom-Workspace, gives it its own /etc/machine-id (the image ships one; an install made earlier gets its own at its next start), boots it. The output is a short summary; the workspace's boot log is folded under Show the boot log. The machine shares the host network, so nothing to configure there.
2 wait-codeserver Probes code-server on the host loopback (default 7380) with a signature check, up to 120 s
3 os-baseline Fills xz-utils on a v27 image; a no-op on later images
4 ensure-adom-bridge-cli Passes if Adom Bridge's direct API answers (127.0.0.1:24680; 8770 is Hydrogen's own). Otherwise installs it when ab's manifest has a linux entry for this account (download, sha256 check, --install --no-launch), starts it hidden through its run.sh and waits up to 2 minutes. No Linux build for the account (or not signed in yet) logs "Skipped" and continues; Hydrogen tries again after sign-in and every 30 minutes
5 test-relay Makes sure the relay inside the workspace answers (restarts adom-relay.service once if not) and is reachable through the code-server proxy; a gate
6 activate-editor Waits for your Adom sign-in (it opens in your browser as soon as the workspace is built), proves the :8821 editor API answers, then binds env vars, api key and relay to this launch
7 verify-setup GATE: re-checks every artifact independently: image floor, code-server, editor API, adom-cli against Adom, the Claude CLI, env vars, relay, the synced layout
8 open-welcome GATE (final): opens welcome.html in the right pane; halts unless the Welcome tab appears

Off by default: test-direct-connect and test-adom-cli run only with HD_SETUP_DIAGNOSTICS=1 or the setup-diagnostics.flag marker (test-direct-connect also skips on Linux when no Adom Bridge is running). update-packages and claude-auth stay in the code behind switches and are off: adom/hook converges packages at boot and every 30 minutes, and Choose your AI handles sign-in after setup.

Former step ids such as set-env-vars, inject-api-key, start-relay, configure-vscode, install-claude-cli, install-brand-fonts, ensure-sse, verify-workspace, welcome, install-hd-skills no longer exist; their work is in the launch hook, the golden image, a package, or a later gate. Do not list or run them.

Common questions

"Why is X installed?" Baked into the golden image (or installed by an Adom package), not a setup step.

"Why did it ask for my password?" Hydrogen never runs as root; starting the nspawn machine needs it. The .deb/.rpm set up a sudoers rule for one helper file; an AppImage, or a user outside the admin groups, gets the same through one pkexec prompt on first run.

"Setup failed at step N" The card shows the error and, when it knows one, the fix: reinstall the package or approve the prompt (helper or systemd-container missing); sudo machinectl terminate Adom-Workspace; sudo machinectl remove Adom-Workspace then Retry (the import failed); sudo machinectl terminate Adom-Workspace then Retry (the machine did not boot). Setup never asks for a restart on Linux. Each step has a Retry button.

"Re-run a step" Setup panel, or POST $(cat ~/.adom/hydrogen-control-url)/setup/step/<id> (body {"continue_after":true} to keep going).

"Re-run all steps" → Click "Run All" in the setup panel; it resumes from the first not-done step. (The old headless POST /setup/run-all is now REFUSED.)

Virgin reset

Virgin reset wipes parts of your workspace so setup can rebuild them cleanly. The ONLY programmatic trigger is POST /setup/panel/run-virgin-reset. Toggle which artifacts to delete (option keys in parentheses):

Toggle (key) What gets wiped When to use
Install step state (install_state) Marks all steps as pending so they re-run Always (default on)
Workspace (container) PRISTINE wipe + re-provision — deletes the workspace AND everything in it, including your project files Always (default on); your work is GONE
Image tarball (tarball, legacy image) Deletes the cached golden image (full re-download) Rarely — only if the image is corrupted
Webview storage (webview_storage), VS Code state (vscode_state) Nothing on Linux: the reset does not touch the WebKitGTK web data Not useful here
Adom session token (adom_token) Deletes hydrogen-session.txt; forces re-login Rarely
Claude credentials (claude_token) Deletes the host-side Claude creds backup; forces Claude re-auth When Claude auth is stuck

confirmed_destructive must be set (body {"options":{...}}; defaults keep auth). After toggling, hit "Wipe Selected", then "Run All" to rebuild. The workspace reset backs up Claude creds first unless claude_token is checked.

The container toggle stops and removes the Adom-Workspace machine (machinectl remove) and everything in it, including /home/adom/project; the next setup imports a fresh one. tarball deletes the cached image in ~/.local/share/Adom/HydrogenDesktop/cache/. The helper manages only Adom-Workspace and refuses any other machine, and the reset performs no reboot. Toggles and the keep-auth testing pattern are in hydrogen-setup.

Setup panel APIs (useful for AI automation)

Endpoint What it does
GET /setup/state Current state — never-run, in-progress, complete, or error
POST /setup/step/<id> Re-run a single named step (optional {"continue_after":true})
POST /setup/panel/run-virgin-reset Trigger virgin reset with the supplied toggle options
POST /setup/panel/show Open the setup panel from anywhere

All on Hydrogen's control API at $(cat ~/.adom/hydrogen-control-url).

Refused: POST /setup/virgin-reset, /setup/run-all, /setup/run-step.

Setup state file

~/.config/hydrogen-desktop/setup-steps-workspace.json (an install made before 2026-11-06 called it setup-steps-wsl.json; Hydrogen renames it the first time it reads it): one entry per step with status, output and percent. Hydrogen reads it at launch to decide whether the setup panel opens.

  • ~/.claude/skills/hydrogen-golden-image/SKILL.md — the baked-image model: what's pre-installed vs. what setup does
  • hydrogen-setup — the setup-panel UX and virgin-reset toggles
  • hydrogen-container: the workspace machine setup builds
  • hydrogen-volume: where files live and what a virgin reset removes