Adom Hydrogen (Linux)
Public Made by Adomby adom
The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.
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,pkexecorsudo -nerrors: 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.
Related skills
hydrogen-setup-steps: each step and what it didhydrogen-golden-image: what the image carrieshydrogen-workspace-lifecycle: start, stop, import, remove mechanics
---
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)
```bash
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`.
## Related skills
- `hydrogen-setup-steps`: each step and what it did
- `hydrogen-golden-image`: what the image carries
- `hydrogen-workspace-lifecycle`: start, stop, import, remove mechanics