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-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-clidownloads 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-bridgeCLI 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:
Ifadom-bridge ping # → {"status":"connected", ...} means a client is reachable adom-bridge status # who's connected + .capabilities + which local apps are installed/runningpingfails, 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
9001is 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
<1500pxbefore 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.
Related skills
- 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:
--targetand the mesh - hydrogen-bridges, hydrogen-file-transfer, hydrogen-notifications, hydrogen-open-url
---
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:
```bash
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:
```bash
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:
```bash
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:**
```bash
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.
## Related skills
- **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**