main
John Lauer Publish 0.1.0 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/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:
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.
  • 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