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-topology description: >- Where Claude runs relative to Hydrogen on Linux: inside the local Adom-Workspace systemd-nspawn machine on the user's Linux computer, or in a cloud container, and how to reach the host and the workspace from each. Use when asked where am I, cloud vs local, reach the host, reach the workspace, machinectl, or adom-bridge relay.
Hydrogen: Topology (Linux)
Up to three environments are involved: the user's Linux computer (where
Hydrogen (ah) runs), Hydrogen's workspace on it (the Adom-Workspace
systemd-nspawn machine, on the same kernel, no VM), and optionally an Adom
cloud container (hc). Where YOU run decides how you reach the others, so check
first: adom-context prints a "Where:" line.
Case 1: you run inside the local workspace (the default on ah)
You (Claude) run inside the Adom-Workspace machine on the user's own Linux computer.
- Your shell,
/home/adom/projectand your repos are in the machine. - The machine shares the host's network: 127.0.0.1 is the same on both sides.
Hydrogen's control API is
$(cat ~/.adom/hydrogen-control-url)(normallyhttp://127.0.0.1:47084), and a port you listen on is reachable from the host's browser athttp://localhost:<port>/directly. - Host files:
/mnt/host/home(read-write, the host's/home),/mnt/host/tmp(read-write),/mnt/host/usrand/mnt/host/opt(read-only). Your own/tmpis private to the machine. Nothing else of the host is visible. - The machine's hostname is the host's name.
- There is no Hydrogen verb that runs a command on the host itself. Hydrogen
for Linux installs and starts Adom Bridge when a Linux build is published for
the user's account, and hands it the workspace relay, so
adom-bridge <verb>reaches it. Check withadom-bridge ping. Without it, desktop verbs (screenshots, KiCad, pup) are unavailable on this computer. adom-bridge --target <name>still reaches the user's OTHER machines (for example their Windows PC) through the Adom mesh when they run Adom Bridge.- Stopping or restarting the machine kills your own shell: do it only when the user asks.
Case 2: you run in a cloud container, driving the user's PC
You (Claude) run inside an Adom cloud Docker container. The user's Linux
computer is a remote target you reach through the adom-bridge CLI relay, and
only if Adom Bridge runs there (adom-bridge targets). There are THREE separate
environments:
1. Cloud Docker (where you run)
- Your shell, your filesystem, your git repos
adom-bridgeCLI connects to Adom Bridge on the user's machines via relay- This container has NOTHING to do with Hydrogen's local workspace
- Restarting the workspace machine does NOT affect you
- You can freely
git push, edit code, run builds here
2. The user's Linux computer
- Hydrogen, the Tauri desktop app
- Adom Bridge, installed and started by Hydrogen when a Linux build is published for the user's account
- You reach it via
adom-bridge --target <linux-box> shell_execute '{"command":"..."}'
3. Hydrogen's workspace (the Adom-Workspace systemd-nspawn machine)
- Machine name:
Adom-Workspace(fixed) - Runs code-server, adom-bridge CLI, relay server
- You reach it through Hydrogen's root helper, which the user may run without a password:
adom-bridge --target <linux-box> shell_execute \
'{"command":"sudo -n /usr/libexec/adom-hydrogen/hydrogen-workspace -d Adom-Workspace -u adom -- ls /home/adom"}'
- This is TWO hops: cloud, relay, the Linux host, the helper, the machine.
The relay chains
Cloud adom-bridge CLI -> cloud relay -> internet -> Adom Bridge on the user's machine -> runs it
Inside the workspace:
Workspace adom-bridge CLI -> local relay (:8765 WS / :8766 HTTP, adom-relay.service)
-> code-server proxy (:7380/proxy/8765/) -> Adom Bridge, when one is connected
The workspace ports (7380, 8765, 8766, 8820, 8821, and any listener inside the machine) are dropped for new connections from the LAN by the helper's nft table; loopback works.
Managing the machine (host side)
machinectl status Adom-Workspace and machinectl list work without root.
Hydrogen itself only acts through the helper, which manages Adom-Workspace
and refuses any other name. Never stop, remove or reconfigure other machines or
containers on the user's computer.
NEVER Do These
- NEVER confuse your cloud container with the user's workspace.
curl http://127.0.0.1:8766/healthin the cloud hits YOUR relay, not the workspace's. - NEVER touch any machine or container other than
Adom-Workspace. Hydrogen's helper refuses any other name; do not work around it. - NEVER assume the workspace's status affects your container. They're completely independent.
- NEVER stop or restart the workspace machine from inside it unless the user asks. It kills your own shell.
- NEVER skip the adom-bridge round-trip test. The relay chain has many links — test end-to-end, not individual parts.
Related skills
hydrogen-container: facts about the workspace machinehydrogen-volume: where files live and how to copy them outhydrogen-networking: ports and the shared localhost
---
name: hydrogen-topology
description: >-
Where Claude runs relative to Hydrogen on Linux: inside the local
Adom-Workspace systemd-nspawn machine on the user's Linux computer, or in a
cloud container, and how to reach the host and the workspace from each. Use
when asked where am I, cloud vs local, reach the host, reach the workspace,
machinectl, or adom-bridge relay.
---
# Hydrogen: Topology (Linux)
Up to three environments are involved: the user's **Linux computer** (where
Hydrogen (ah) runs), Hydrogen's **workspace** on it (the `Adom-Workspace`
systemd-nspawn machine, on the same kernel, no VM), and optionally an **Adom
cloud container** (hc). Where YOU run decides how you reach the others, so check
first: `adom-context` prints a "Where:" line.
## Case 1: you run inside the local workspace (the default on ah)
You (Claude) run inside the `Adom-Workspace` machine on the user's own Linux computer.
- Your shell, `/home/adom/project` and your repos are in the machine.
- The machine shares the host's network: 127.0.0.1 is the same on both sides.
Hydrogen's control API is `$(cat ~/.adom/hydrogen-control-url)` (normally
`http://127.0.0.1:47084`), and a port you listen on is reachable from the
host's browser at `http://localhost:<port>/` directly.
- Host files: `/mnt/host/home` (read-write, the host's `/home`), `/mnt/host/tmp`
(read-write), `/mnt/host/usr` and `/mnt/host/opt` (read-only). Your own `/tmp`
is private to the machine. Nothing else of the host is visible.
- The machine's hostname is the host's name.
- There is no Hydrogen verb that runs a command on the host itself. Hydrogen
for Linux installs and starts Adom Bridge when a Linux build is published for
the user's account, and hands it the workspace relay, so `adom-bridge <verb>`
reaches it. Check with `adom-bridge ping`. Without it, desktop verbs
(screenshots, KiCad, pup) are unavailable on this computer.
- `adom-bridge --target <name>` still reaches the user's OTHER machines (for
example their Windows PC) through the Adom mesh when they run Adom Bridge.
- Stopping or restarting the machine kills your own shell: do it only when the
user asks.
## Case 2: you run in a cloud container, driving the user's PC
You (Claude) run inside an **Adom cloud Docker container**. The user's Linux
computer is a remote target you reach through the `adom-bridge` CLI relay, and
only if Adom Bridge runs there (`adom-bridge targets`). There are THREE separate
environments:
### 1. Cloud Docker (where you run)
- Your shell, your filesystem, your git repos
- `adom-bridge` CLI connects to Adom Bridge on the user's machines via relay
- This container has NOTHING to do with Hydrogen's local workspace
- Restarting the workspace machine does NOT affect you
- You can freely `git push`, edit code, run builds here
### 2. The user's Linux computer
- **Hydrogen**, the Tauri desktop app
- **Adom Bridge**, installed and started by Hydrogen when a Linux build is published for the user's account
- You reach it via `adom-bridge --target <linux-box> shell_execute '{"command":"..."}'`
### 3. Hydrogen's workspace (the `Adom-Workspace` systemd-nspawn machine)
- Machine name: `Adom-Workspace` (fixed)
- Runs code-server, adom-bridge CLI, relay server
- You reach it through Hydrogen's root helper, which the user may run without a password:
```bash
adom-bridge --target <linux-box> shell_execute \
'{"command":"sudo -n /usr/libexec/adom-hydrogen/hydrogen-workspace -d Adom-Workspace -u adom -- ls /home/adom"}'
```
- This is TWO hops: cloud, relay, the Linux host, the helper, the machine.
## The relay chains
```
Cloud adom-bridge CLI -> cloud relay -> internet -> Adom Bridge on the user's machine -> runs it
```
Inside the workspace:
```
Workspace adom-bridge CLI -> local relay (:8765 WS / :8766 HTTP, adom-relay.service)
-> code-server proxy (:7380/proxy/8765/) -> Adom Bridge, when one is connected
```
The workspace ports (7380, 8765, 8766, 8820, 8821, and any listener inside the
machine) are dropped for new connections from the LAN by the helper's nft table;
loopback works.
## Managing the machine (host side)
`machinectl status Adom-Workspace` and `machinectl list` work without root.
Hydrogen itself only acts through the helper, which manages `Adom-Workspace`
and refuses any other name. Never stop, remove or reconfigure other machines or
containers on the user's computer.
## NEVER Do These
1. **NEVER confuse your cloud container with the user's workspace.**
`curl http://127.0.0.1:8766/health` in the cloud hits YOUR relay, not the workspace's.
2. **NEVER touch any machine or container other than `Adom-Workspace`.**
Hydrogen's helper refuses any other name; do not work around it.
3. **NEVER assume the workspace's status affects your container.**
They're completely independent.
4. **NEVER stop or restart the workspace machine from inside it unless the user asks.**
It kills your own shell.
5. **NEVER skip the adom-bridge round-trip test.**
The relay chain has many links — test end-to-end, not individual parts.
## Related skills
- `hydrogen-container`: facts about the workspace machine
- `hydrogen-volume`: where files live and how to copy them out
- `hydrogen-networking`: ports and the shared localhost