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-doctor description: >- The Hydrogen Doctor on Linux: a one-click health scan of the whole stack (workspace machine, code-server, Claude, Adom auth, ports, relay, Adom Bridge), also at GET/POST /doctor. Use when something is broken and nobody knows what, things are weird after the computer sleeps, or to run the doctor.
Hydrogen Doctor: diagnose the whole stack in one place
The Doctor answers "is everything actually working?" with evidence: about 20 real checks end to end (not "is the process alive" but "does it answer correctly"), each with a plain-English explanation.
Where it lives
- UI: Adom menu (top-left) → Doctor.... A dialog lists every check with a green/red state; hovering a row reveals a paragraph explaining what that check means and why it matters. Buttons: Re-run checks, Fix problems, and (only when recommended) Restart workspace.
- API (Hydrogen control API, see
hydrogen-apifor the port):GET /doctorruns all checks:{before: {checks: [...]}, still_failing, ...}, each check withokandmessage.POST /doctorbody{"fix": true}runs checks, tries the safe fix (none exists on Linux yet, see below), and returns{before, after, actions, still_failing, recommend_workspace_restart}.
What it checks
Workspace side: the workspace helper responds (the helper hydrogen-workspace and
machinectl answer), the runtime is the Adom-Workspace systemd-nspawn machine
(workspace), the Adom API key exists (api-key), required env vars are exported
(env-vars), adom-cli is installed (adom-cli) and can actually reach Adom's cloud
(adom-cli-api), skills are deployed (skills), the in-container relay answers on
8765/8766 (relay).
Editor side: code-server is genuinely serving (code-server, the big one after
sleep), the required extensions are installed (extensions), Claude Code CLI is
installed (claude-installed) and signed in (claude-auth), the live SSE link
between editor and app is up (sse), the workspace-layout API responds
(webview).
Plumbing: workspace service ports reachable from this computer (ports), identity
(identity), the relay path for Adom Bridge (adom-bridge), ab's direct API
(adom-bridge-direct), and port-integrity (code-server serving; a control API that moved
off 47084 is a note, not a failure).
adom-bridge-direct is red whenever no Adom Bridge runs on this computer. Hydrogen installs and
starts it when a Linux build is published for the user's account, so red is expected only when
none is published yet (the setup step says so). If one is installed (~/.local/share/adom-bridge-app/run.sh)
and it stays red, read the [ab-linux] and [ad-supervisor] log lines.
Repair on Linux
- Fix problems has no automatic heal on Linux: the heal cascade it triggers exists only on
the other platforms, so
actionssays "Heal cascade unavailable" and the checks are not re-run. Read the failures and fix them directly. - Restart workspace (disruptive, confirm-gated):
POST /container-restartstops the machine and starts it again, reloading VS Code and Claude ({"dry_run":true}says what it would do). Never trigger it without the user's OK. - A red "Workspace helper responds" means the helper or
machinectldid not answer: restart the workspace from the Adom menu, then restart Hydrogen if that does not help.
How you (the AI) should use it
- User says "nothing works" or "it froze after I opened my laptop": call
GET /doctorfirst and READ the failures instead of guessing. - Fix what the failures name (restart a service, sign in, start code-server).
- Offer a workspace restart only when the failures point at the machine itself, and ask first.
- After any repair, re-run
GET /doctorand only claim health you can see (allok: true).
Related skills
hydrogen-wake-repair: what happens after sleep on Linux (the Cannot reconnect watcher).hydrogen-workspace-lifecycle: what a workspace restart actually does.hydrogen-api: how to find the control port.
---
name: hydrogen-doctor
description: >-
The Hydrogen Doctor on Linux: a one-click health scan of the whole stack (workspace
machine, code-server, Claude, Adom auth, ports, relay, Adom Bridge), also at GET/POST
/doctor. Use when something is broken and nobody knows what, things are weird after the
computer sleeps, or to run the doctor.
---
# Hydrogen Doctor: diagnose the whole stack in one place
The Doctor answers "is everything actually working?" with evidence: about 20 real checks
end to end (not "is the process alive" but "does it answer correctly"), each with a
plain-English explanation.
## Where it lives
- **UI**: Adom menu (top-left) → **Doctor...**. A dialog lists every check with
a green/red state; hovering a row reveals a paragraph explaining what that
check means and why it matters. Buttons: **Re-run checks**, **Fix problems**,
and (only when recommended) **Restart workspace**.
- **API** (Hydrogen control API, see `hydrogen-api` for the port):
- `GET /doctor` runs all checks: `{before: {checks: [...]}, still_failing, ...}`, each check
with `ok` and `message`.
- `POST /doctor` body `{"fix": true}` runs checks, tries the safe fix (none exists on Linux
yet, see below), and returns
`{before, after, actions, still_failing, recommend_workspace_restart}`.
## What it checks
Workspace side: the workspace helper responds (the helper `hydrogen-workspace` and
`machinectl` answer), the runtime is the `Adom-Workspace` systemd-nspawn machine
(`workspace`), the Adom API key exists (`api-key`), required env vars are exported
(`env-vars`), `adom-cli` is installed (`adom-cli`) and can actually reach Adom's cloud
(`adom-cli-api`), skills are deployed (`skills`), the in-container relay answers on
8765/8766 (`relay`).
Editor side: code-server is genuinely serving (`code-server`, the big one after
sleep), the required extensions are installed (`extensions`), Claude Code CLI is
installed (`claude-installed`) and signed in (`claude-auth`), the live SSE link
between editor and app is up (`sse`), the workspace-layout API responds
(`webview`).
Plumbing: workspace service ports reachable from this computer (`ports`), identity
(`identity`), the relay path for Adom Bridge (`adom-bridge`), ab's direct API
(`adom-bridge-direct`), and `port-integrity` (code-server serving; a control API that moved
off 47084 is a note, not a failure).
**`adom-bridge-direct` is red whenever no Adom Bridge runs on this computer.** Hydrogen installs and
starts it when a Linux build is published for the user's account, so red is expected only when
none is published yet (the setup step says so). If one is installed (`~/.local/share/adom-bridge-app/run.sh`)
and it stays red, read the `[ab-linux]` and `[ad-supervisor]` log lines.
## Repair on Linux
- **Fix problems** has no automatic heal on Linux: the heal cascade it triggers exists only on
the other platforms, so `actions` says "Heal cascade unavailable" and the checks are not
re-run. Read the failures and fix them directly.
- **Restart workspace** (disruptive, confirm-gated): `POST /container-restart` stops the
machine and starts it again, reloading VS Code and Claude (`{"dry_run":true}` says what it
would do). Never trigger it without the user's OK.
- A red "Workspace helper responds" means the helper or `machinectl` did not answer: restart the workspace from
the Adom menu, then restart Hydrogen if that does not help.
## How you (the AI) should use it
- User says "nothing works" or "it froze after I opened my laptop": call
`GET /doctor` first and READ the failures instead of guessing.
- Fix what the failures name (restart a service, sign in, start code-server).
- Offer a workspace restart only when the failures point at the machine itself, and ask first.
- After any repair, re-run `GET /doctor` and only claim health you can see
(all `ok: true`).
## Related skills
- `hydrogen-wake-repair`: what happens after sleep on Linux (the Cannot reconnect watcher).
- `hydrogen-workspace-lifecycle`: what a workspace restart actually does.
- `hydrogen-api`: how to find the control port.