main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-adom-bridge description: >- What Hydrogen (ah) and Adom Bridge (ab) are on Linux and how they work together: ab is your hands on a real computer (files, shell, OS screenshots, apps, KiCad), Hydrogen installs and starts it here when a Linux build is published for the user's account, and the adom-bridge CLI also reaches the user's other machines. Use when asked what can you do on my computer, run a command on my PC, screenshot my screen, or send a file to my desktop.

Hydrogen and Adom Bridge on Linux: your reach onto real machines

You (the AI) run inside the Hydrogen workspace, the Adom-Workspace systemd-nspawn machine on the user's Linux computer. That's a sandbox. Adom Bridge (ab) is how you reach OUT of it onto the user's actual operating system — their real files, shell, screen, and desktop apps. Knowing ab exists is the difference between "I can only work in here" and "I can create that file on your Desktop, screenshot your screen, and open it in KiCad."

The Linux reality

  • Hydrogen for Linux installs and runs ab when ab's manifest publishes a Linux build for the user's account (insiders first, everyone once it is promoted). Setup step ensure-adom-bridge-cli downloads the AppImage, checks its sha256, installs it (--install --no-launch, one per-user copy in ~/.local/share/adom-bridge-app) and starts it hidden; Hydrogen restarts it if it dies and applies its staged updates. Before that, or with no Linux build for the account, there are no desktop verbs (desktop screenshots, files to the desktop, KiCad, pup, Grok Bot) on THIS computer.
  • Hydrogen adopts ab (one it installed, or one the user runs): it hands ab the workspace relay and the Adom session (POST /embedded/enter) and ab works as on any other desktop. See hydrogen-embedded-bridge.
  • The user's OTHER machines still answer. The adom-bridge CLI in the workspace reaches every machine on the user's Adom mesh that runs ab (for example their Windows PC or a Mac): adom-bridge targets, then --target <name>. Never guess which machine: ask.

To see which machines answer and whether ab runs on this computer:

adom-bridge targets               # every machine on the mesh
BASE="$(cat ~/.adom/hydrogen-control-url)"
curl -s "$BASE/ab/process"        # ab processes on THIS Linux host (none = not running here)
curl -s "$BASE/ab/health"         # ab's direct API, as Hydrogen sees it

What ab lets you do (once a machine answers)

All via the adom-bridge CLI from inside the workspace. Rather than re-document every verb here, this is a capability map → the focused skill:

Capability Verb(s) / surface Where it's documented
Files to / from the machine send_files, pull_file, list_files, watch_files hydrogen-file-transfer
Shell command on the machine shell_execute, run_script (base64 script, no quoting) shell trust below
Screenshots and window control desktop_screenshot_*, desktop_list_windows, desktop_set_window_state adom-bridge-window-capture
Screen recording desktop_record_*, pup_record_* hydrogen-recording
Notifications notify_user hydrogen-notifications
Browsers (pup) pup_* hydrogen-open-url, pup
KiCad and other EDA bridges kicad_*, fusion_*, ... hydrogen-bridges

For the complete verb list run adom-bridge list_commands.

A bridge without a Linux build answers unsupported_on_this_os on a Linux ab.

Host shell-trust model

shell_execute really runs on the target machine. Approvals are the human's: see adom-bridge-permissions. Revoke a standing auto-approval at any time:

adom-bridge shell_auto_approve '{"duration_secs":0}'   # turn auto-approve off now

When you don't need a free-form shell, prefer the no-escape structured runners over hand-quoted shell_execute (ab ≥ 1.8.50): adom-bridge run_script '{"interpreter":"bash","scriptB64":"<b64>"}'. Base64 the script so no quoting survives to be mangled.

Talking to Hydrogen itself

You do not need ab for that. Hydrogen's control API is on the shared loopback:

BASE="$(cat ~/.adom/hydrogen-control-url)"   # normally http://127.0.0.1:47084
curl -s "$BASE/health"
curl -s "$BASE/setup/state"

See hydrogen-api.

How the connection works (and how you check it)

You (AI in the workspace)
  -> adom-bridge <verb> '<json>'          CLI in the workspace
     -> relay (adom-relay.service: WS :8765, HTTP :8766, inside the workspace)
        -> ab on this computer (when it runs)
        -> the Adom mesh -> ab on the user's other machines
  • The workspace shares the host's network, so the relay's ports are this computer's localhost:8765/8766; Hydrogen's firewall table keeps them off the LAN. See hydrogen-networking.
  • Always verify the bridge before acting on the host:
    adom-bridge ping       # → {"status":"connected", ...} means a client is reachable
    adom-bridge status     # who's connected + .capabilities + which local apps are installed/running
    
    If ping fails, no desktop client is connected: tell the user plainly that no Adom Bridge answers. Offer to use another machine of theirs, or point them at adom-bridge-linux to install it here. Don't claim you acted on a machine without a successful round-trip.

What NOT to do

  • Never kill ab on a machine you are driving: it is your control channel.
  • Port 9001 is Hydrogen's liveness beacon for ab, not its control API (read ~/.adom/hydrogen-control-url).
  • Don't broad-kill node — VS Code Server runs as node; killing it kills the whole workspace.
  • Resize screenshots to <1500px before reading them, and inject every screenshot into shotlog with a real description.

Mental model for answering the user

When the user asks for something that lives on a real computer ("save this to my Desktop", "what's on my screen", "open this in KiCad", "run this command on my machine"), that's an ab job: find which machine answers (adom-bridge targets) and ask which one when more than one could be meant. When it's about the workspace itself (editor, files under /home/adom/project, the runtime), that's Hydrogen. Verify with adom-bridge ping, then act.

  • hydrogen-embedded-bridge: how a user-run Linux ab is adopted by Hydrogen
  • adom-bridge-linux: installing and updating ab on Linux
  • adom-bridge-multi-machine, adom-bridge-mesh: --target and the mesh
  • hydrogen-bridges, hydrogen-file-transfer, hydrogen-notifications, hydrogen-open-url