main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-adom-bridge-triage description: >- Triage Adom Bridge (ab) when a Hydrogen workspace on Linux cannot reach it: which half is broken, whether ab is even running on this Linux desktop, its app.log, the /ab/* probes, reaching the user's other machines through the mesh. Use when ab won't connect, no desktop client connected, ab never starts, or the bridge keeps dying.

Parent skill: hydrogen-adom-bridge (works with hydrogen-doctor, adom-bridge-linux, adom-bridge)

Triage: Adom Bridge won't connect

First fact: Hydrogen on Linux installs and supervises Adom Bridge only when ab's manifest has a Linux build for the user's account. The setup step ensure-adom-bridge-cli says which case this is ("No Adom Bridge for Linux is published for your account yet" means none was installed). When it is installed (~/.local/share/adom-bridge-app/run.sh exists), Hydrogen starts it hidden and restarts it when it dies, so "No desktop client connected" then means it is crash-looping or signed out: read ~/.local/share/adom-bridge-app/app.log and the [ab-linux] / [ad-supervisor] lines of Hydrogen's log.

ping returning "No desktop client connected" tells you only that the desktop half is absent. It does not tell you whether ab is uninstalled, signed out, misconfigured, or installed and crash-looping. Those need opposite fixes, and the last one is invisible from the container unless you go looking for it.

The ladder, cheapest first

1. Which half is broken? (container-side, free)

curl -sf http://127.0.0.1:8766/health     # connectedClients, usingDefaultToken
adom-bridge --ai-thread "<your thread>" ping
adom-bridge --ai-thread "<your thread>" targets

connectedClients: 0 with a healthy relay ⇒ the container is fine; every remaining step is about the desktop. Do not start reconfiguring the container.

targets may list the user's OTHER machines (for example their Windows PC or a laptop). Those are reachable through the Adom mesh even when this Linux desktop has no ab: pass --target <name>. Ask which machine the user means; never guess.

2. Ask Hydrogen (it sees the host without ab)

The workspace shares the host's network, so the control API is local:

BASE="$(cat ~/.adom/hydrogen-control-url)"   # normally http://127.0.0.1:47084
curl -s "$BASE/ab/health"     | python3 -m json.tool   # one roll-up of the probes below
curl -s "$BASE/ab/process"                             # ab processes on the HOST
curl -s "$BASE/ab/direct-api"                          # ab's API on 127.0.0.1:24680?
curl -s "$BASE/ab/discovery-file"                      # ~/.adom/direct-api-port live or stale
curl -s "$BASE/ab/embedded"
curl -s "$BASE/ab/relay"

/ab/process on Linux lists host processes named adom-bridge and ignores the workspace's own relay process (same name, inside machine.slice). count: 0 means ab is not running on this desktop: go to step 4.

3. ab is running but not attached

Hydrogen hands a running ab the workspace relay and the Adom session (POST /embedded/enter, relay name hydrogen) within about 10 to 20 seconds of seeing it, and again when ab restarts, the relay moves, or the session changes. If ab answers on 24680 but ping still fails a minute later:

  • Check ab is signed in (its own window: tray menu > Open Adom Bridge).

  • Read ab's log on the host. With the usual run.sh launcher it is ~/.local/share/adom-bridge-app/app.log. From the workspace the host's home is /mnt/host/home/<user>/ (file permissions permitting):

    ls -l /mnt/host/home/*/.local/share/adom-bridge-app/app.log
    tail -60 /mnt/host/home/*/.local/share/adom-bridge-app/app.log
    

    A log whose mtime keeps advancing with the same panic means ab is crash-looping. Compare its version (adom-bridge-app.AppImage --version, safe: it never starts a copy) with adom-wiki release list adom/adom-bridge.

4. ab is not on this desktop

That is the normal state. Either:

  • work through another machine on the mesh (--target <name>), or
  • tell the user that desktop features on this Linux machine (screenshots, files to the desktop, KiCad, pup) need the Linux Adom Bridge, and point them at the adom-bridge-linux skill for the one-copy install. Grok Bot shows "needs Adom Bridge" for the same reason.

The out-of-band channels (why you are not blind)

When ab is dead you have not lost the host — you have lost one route to it.

  1. Hydrogen's control API — 127.0.0.1:47084, always up if Hydrogen is running. Diagnostics, ports, container state. See hydrogen-api.
  2. The host's files under /mnt/host. The workspace never runs host programs directly; there is no interop channel. Reading the host's files under /mnt/host (home, /tmp, read-only /usr and /opt) is the out-of-band view.

Do NOT do these while guessing

Don't Why
register_container for this workspace Hydrogen already attaches ab as hydrogen; a second entry is a duplicate path the user sees in Connections and writes three cloud keys.
Rotate the relay auth token Adds a mismatch to a system that is already broken.
POST /setup/run-step Marked destructive; refuses without a visible UI. Not a debugging tool.
Conclude "broken" from ping alone on Linux Most Linux desktops simply have no ab.
Start a second ab copy by hand Two copies share one identity and knock each other off the relay. Use the locked run.sh or systemctl --user start adom-bridge-app.
Restart the relay, re-register, re-sign-in as a first move All container-side; none of them touch a desktop process that is panicking.

Reverting a mistaken register_container

If you (or a previous agent) registered a container that should not exist, removing it locally is not enough — ab re-reads the cloud profile at boot, at sign-in, and hourly, so a local-only removal comes back. Remove both:

TOK=$(cat /var/run/adom/api-key)

# 1. cloud profile (the authoritative copy)
curl -s -X PATCH https://carbon.adom.inc/user/hydrogen/settings \
  -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
  -d '{"key":"bridge.container.<id>","value":null}'

# 2. ab's local list
adom-bridge --ai-thread "<thread>" \
  server_remove '{"name":"<name>","reason":"<why>"}'

register_container writes bridge.container.<id>, bridge.last_slug, and bridge.enabled. bridge.last_slug will be left pointing at the entry you just deleted; null it too. Its previous value is not recoverable — which is the real argument for not calling register_container speculatively.

Verify with server_list and by re-reading hydrogen_preferences.settings (see hydrogen-key-values). Removing a relay entry you are talking through severs your own transport (adom/adom-bridge#387) — check ping's transport field first; if it says direct-http you are on the loopback API and a relay entry removal cannot cut you off.

Gotchas that cost time

  • ab's direct API is 127.0.0.1:24680; ~/.adom/direct-api-port on the host is authoritative (a stale file plus a silent port is a crash signal).
  • Caller identity is mandatory. Verbs refuse with errorCode: caller_identity_required unless you pass --ai-thread "<a name the user would recognize>". Gated verbs additionally need a per-call reason. See adom-bridge-caller-identity.
  • Quitting Hydrogen asks ab to shut down when Settings > Adom Bridge > "Close Adom Bridge when you quit Hydrogen" is on (the default). Whether ab comes back then depends on how the user launches it (autostart, systemd unit), not on Hydrogen.

When it is genuinely not a crash

If ab's log is old and quiet and no ab process exists on the host, ab is simply not on this desktop: see step 4 and adom-bridge-linux. If ab runs and is signed in but the workspace's connection is missing from its Connections list, follow adom-bridge / adom-bridge-auth. The point of this skill is to make you prove that before you go there.