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-embedded-bridge description: >- How Hydrogen (ah) on Linux relates to Adom Bridge (ab): Hydrogen installs ab when a Linux build is published for the user's account, starts it hidden, restarts it and applies its updates, and ab enters embedded mode with the workspace relay and session from Hydrogen. Use when asked embedded vs standalone, why ab is not installed, why two apps, or where ab's tray went.
Hydrogen and ab on Linux: installed, embedded and supervised
Hydrogen for Linux installs and supervises Adom Bridge, following ab's own Linux install:
- Install: when ab is missing, Hydrogen reads ab's manifest (insiders with the user's Adom
session, else public) and uses its
linuxentry. Nolinuxentry for this account means no ab yet: setup says so and Hydrogen checks again after sign-in and every 30 minutes. It downloads the AppImage (about 150 MB, never bundled with Hydrogen), checks the published sha256, and runs<AppImage> --install --no-launch: one per-user copy in~/.local/share/adom-bridge-app, its lockedrun.sh, a menu entry and login autostart (see adom-bridge-linux). - Start:
~/.local/share/adom-bridge-app/run.sh --embedded --start-hidden --panel-collapsed(the Windows spawn flags; without--embeddeda first start shows ab's window). run.sh's lock keeps one copy. - Supervise: when ab's direct API (
127.0.0.1:24680, or the port in~/.adom/direct-api-port) stops answering and no ab process exists, Hydrogen starts it again through run.sh, with a growing wait if it keeps dying. A copy the user started by hand is never started twice or replaced. - Update: ab updates itself. In embedded mode it stages the update and waits; Hydrogen sends
POST /update/applywhen ab is idle, ab swaps its AppImage and comes back through run.sh. Hydrogen never reinstalls an ab that is present.
This skill explains how the two interact so you can answer "why isn't ab in my tray?", "should I have two installs?", "why did the tray icon disappear?" and similar.
How Hydrogen adopts ab
ab finds Hydrogen on its own: it reads the control port from
~/.config/hydrogen-desktop/ports.json, and Hydrogen answers ab's embedded probe on its
liveness beacon 127.0.0.1:9001. Hydrogen then:
- hands ab the workspace relay and the Adom session with
POST /embedded/enter(relay_name: "hydrogen"), checking every 10 to 20 s and re-sending when ab restarts, the relay changes port, or the session changes; - starts it only through ab's own
run.sh(above), so ab's autostart entry, a systemd user unit or a hand start never make a second copy.
In embedded mode ab hides its own tray icon; Hydrogen's tray menu (the desktop's tray, AppIndicator) carries Open Adom Bridge, which shows ab's window. The rest of that menu: Open Hydrogen (first, GNOME has no left-click action), New Claude/Codex/Antigravity chat (installed AIs only, Kimi with show_kimi), Annotate screen, Open Adom Bridge, Settings, Quit Hydrogen.
On quit
Quitting Hydrogen releases ab. With Settings > Adom Bridge > "Close Adom Bridge when you quit
Hydrogen" on (the default) Hydrogen asks ab to shut down; off, it sends
POST /embedded/release and ab decides whether to exit or go standalone.
Checks
BASE="$(cat ~/.adom/hydrogen-control-url)"
curl -s "$BASE/ab/embedded" # ab's own embedded_status
curl -s "$BASE/ab/process" # ab processes on the host (0 = not running here)
curl -s "$BASE/ab/liveness-beacon" # :9001
ab's direct API is 127.0.0.1:24680 (POST /command with
{"app":"desktop","command":"embedded_status","args":{}}). The workspace shares the host's
loopback, so it reaches that port directly.
Runtime transitions
ab ≥ v1.8.47 re-checks Hydrogen's liveness every 60s during runtime, not just at boot. This is the normal daily cycle for most users, not an edge case:
- User starts ab while Hydrogen runs: ab's next poll finds Hydrogen's beacon on :9001, ab embeds, its tray hides
- User quits Hydrogen with "Close Adom Bridge when you quit Hydrogen" off: ab's next poll fails the Hydrogen probe, ab reverts to standalone, its tray reappears
- User launches Hydrogen again: ab's next poll succeeds, ab re-embeds, its tray hides
The same ab process can flip mode back and forth indefinitely across a Hydrogen-quit / Hydrogen-relaunch cycle. Transitions:
| Current mode | Hydrogen probe says | What ab does |
|---|---|---|
| Standalone | dead | stay standalone (no-op) |
| Standalone | alive | → embed: hide tray, write marker, hide main window, show "Embedded · Hydrogen" pill |
| Embedded | dead | → unembed: show tray, delete marker, hide pill (main window left as-is) |
| Embedded | alive | stay embedded (refresh marker heartbeat in last_seen) |
Both transitions emit a mode-changed event so the frontend can update the footer pill in real time.
Common questions
- "Why isn't Adom Bridge installed?" Hydrogen for Linux does not set it up yet. Without it,
desktop features that go through ab (desktop screenshots, files to the desktop, KiCad, pup,
Grok Bot) are unavailable on this machine. Other machines on the user's mesh still answer
adom-bridge --target <name>. - "Is two apps normal?" Yes: Hydrogen and ab are separate apps. Removing Hydrogen's package leaves ab in place.
- "ab's tray icon appeared." Hydrogen is not running (or quit), so ab went standalone.
---
name: hydrogen-embedded-bridge
description: >-
How Hydrogen (ah) on Linux relates to Adom Bridge (ab): Hydrogen installs ab
when a Linux build is published for the user's account, starts it hidden,
restarts it and applies its updates, and ab enters embedded mode with the
workspace relay and session from Hydrogen. Use when asked embedded vs
standalone, why ab is not installed, why two apps, or where ab's tray went.
---
# Hydrogen and ab on Linux: installed, embedded and supervised
**Hydrogen for Linux installs and supervises Adom Bridge**, following ab's own Linux install:
- **Install:** when ab is missing, Hydrogen reads ab's manifest (insiders with the user's Adom
session, else public) and uses its `linux` entry. No `linux` entry for this account means no
ab yet: setup says so and Hydrogen checks again after sign-in and every 30 minutes. It downloads
the AppImage (about 150 MB, never bundled with Hydrogen), checks the published sha256, and runs
`<AppImage> --install --no-launch`: one per-user copy in `~/.local/share/adom-bridge-app`, its
locked `run.sh`, a menu entry and login autostart (see **adom-bridge-linux**).
- **Start:** `~/.local/share/adom-bridge-app/run.sh --embedded --start-hidden --panel-collapsed` (the Windows spawn flags; without `--embedded` a first start shows ab's window). run.sh's lock keeps one copy.
- **Supervise:** when ab's direct API (`127.0.0.1:24680`, or the port in `~/.adom/direct-api-port`) stops
answering and no ab process exists, Hydrogen starts it
again through run.sh, with a growing wait if it keeps dying. A copy the user started by hand
is never started twice or replaced.
- **Update:** ab updates itself. In embedded mode it stages the update and waits; Hydrogen sends
`POST /update/apply` when ab is idle, ab swaps its AppImage and comes back through run.sh.
Hydrogen never reinstalls an ab that is present.
This skill explains how the two interact so you can answer "why isn't ab in my tray?", "should I have two installs?", "why did the tray icon disappear?" and similar.
## How Hydrogen adopts ab
ab finds Hydrogen on its own: it reads the control port from
`~/.config/hydrogen-desktop/ports.json`, and Hydrogen answers ab's embedded probe on its
liveness beacon `127.0.0.1:9001`. Hydrogen then:
- hands ab the workspace relay and the Adom session with `POST /embedded/enter`
(`relay_name: "hydrogen"`), checking every 10 to 20 s and re-sending when ab restarts, the
relay changes port, or the session changes;
- starts it only through ab's own `run.sh` (above), so ab's autostart entry, a systemd user unit
or a hand start never make a second copy.
In embedded mode ab hides its own tray icon; Hydrogen's tray menu (the desktop's tray, AppIndicator)
carries **Open Adom Bridge**, which shows ab's window. The rest of that menu: Open Hydrogen
(first, GNOME has no left-click action), New Claude/Codex/Antigravity chat (installed AIs only,
Kimi with show_kimi), Annotate screen, Open Adom Bridge, Settings, Quit Hydrogen.
## On quit
Quitting Hydrogen releases ab. With Settings > Adom Bridge > "Close Adom Bridge when you quit
Hydrogen" on (the default) Hydrogen asks ab to shut down; off, it sends
`POST /embedded/release` and ab decides whether to exit or go standalone.
## Checks
```bash
BASE="$(cat ~/.adom/hydrogen-control-url)"
curl -s "$BASE/ab/embedded" # ab's own embedded_status
curl -s "$BASE/ab/process" # ab processes on the host (0 = not running here)
curl -s "$BASE/ab/liveness-beacon" # :9001
```
ab's direct API is `127.0.0.1:24680` (`POST /command` with
`{"app":"desktop","command":"embedded_status","args":{}}`). The workspace shares the host's
loopback, so it reaches that port directly.
## Runtime transitions
**ab ≥ v1.8.47** re-checks Hydrogen's liveness every 60s during runtime, not just at boot. This is the normal daily cycle for most users, not an edge case:
- User starts ab while Hydrogen runs: ab's next poll finds Hydrogen's beacon on :9001, ab
embeds, its tray hides
- User quits Hydrogen with "Close Adom Bridge when you quit Hydrogen" off: ab's next poll fails
the Hydrogen probe, ab reverts to standalone, its tray reappears
- User launches Hydrogen again: ab's next poll succeeds, ab re-embeds, its tray hides
The same ab process can flip mode back and forth indefinitely across a Hydrogen-quit / Hydrogen-relaunch cycle. Transitions:
| Current mode | Hydrogen probe says | What ab does |
|---|---|---|
| Standalone | dead | stay standalone (no-op) |
| Standalone | alive | → **embed**: hide tray, write marker, hide main window, show "Embedded · Hydrogen" pill |
| Embedded | dead | → **unembed**: show tray, delete marker, hide pill (main window left as-is) |
| Embedded | alive | stay embedded (refresh marker heartbeat in `last_seen`) |
Both transitions emit a `mode-changed` event so the frontend can update the footer pill in real time.
## Common questions
- **"Why isn't Adom Bridge installed?"** Hydrogen for Linux does not set it up yet. Without it,
desktop features that go through ab (desktop screenshots, files to the desktop, KiCad, pup,
Grok Bot) are unavailable on this machine. Other machines on the user's mesh still answer
`adom-bridge --target <name>`.
- **"Is two apps normal?"** Yes: Hydrogen and ab are separate apps. Removing Hydrogen's package
leaves ab in place.
- **"ab's tray icon appeared."** Hydrogen is not running (or quit), so ab went standalone.