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-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.
Related skills
~/.claude/skills/hydrogen-golden-image/SKILL.md— the baked-image model: what's pre-installed vs. what setup doeshydrogen-setup— the setup-panel UX and virgin-reset toggleshydrogen-container: the workspace machine setup buildshydrogen-volume: where files live and what a virgin reset removes
---
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.
## Related skills
- `~/.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