main
John Lauer Publish 0.1.0 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 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

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.