main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-networking description: >- Port architecture, hostnames and networking rules for the Hydrogen workspace on Linux: one shared localhost with the host, the control URL, the code-server proxy, relay ports, LAN protection. Read before adding a port or exposing a service. Use for Hydrogen ports, loopback, proxy, or 7380/8770.

THE ONE RULE: the workspace shares this computer's network, so a port bound inside the workspace is http://localhost:<port>/ on the host, and the other way round. Webviews, browsers and host tools use the direct form. /proxy/<port>/ through code-server is only a fallback.

Hydrogen — Networking & Port Architecture

The workspace is the systemd-nspawn machine Adom-Workspace, started with no virtual network (VirtualEthernet=no, Private=no in /etc/systemd/nspawn/Adom-Workspace.nspawn). It lives in the host's network namespace:

  • 127.0.0.1 is the same interface on both sides. No forwarding, no port mapping, no gateway IP.
  • A port can only be bound once on the whole computer. A dev server in the workspace and a host program cannot both listen on 5173.
  • ss -ltn or /proc/net/tcp inside the workspace also lists the host's listeners. Hydrogen's Ports window tells them apart by cgroup: processes in machine.slice are the workspace's.

Kept off the LAN

Because the network is shared, a workspace service that binds 0.0.0.0 would be reachable from other computers. Hydrogen's root helper installs its own nft table inet adom_hydrogen (iptables fallback) on every machine start: new inbound connections to 7380, 8765, 8766, 8820, 8821 and to any listener owned by machine.slice are dropped (that last match needs nft cgroup v2 socket support; without it only the listed ports are covered); loopback and replies pass. Bind 127.0.0.1 by default anyway: it is reachable from this computer and never from the network.

Workspace services

Port Service From the host
7380 code-server (VS Code), bound 127.0.0.1 localhost:7380
8765 relay WebSocket localhost:8765 or /proxy/8765/
8766 relay HTTP localhost:8766 or /proxy/8766/
8820 shotlog localhost:8820
8821 adom-vscode editor-control API localhost:8821
5173 your dev server localhost:5173

Hydrogen's own ports (in the adom-hydrogen process on the host)

Port Service Notes
47080 Discovery tries 47080, 48080, 49180, 50280; first free wins
47083 Reverse proxy (proxy) dynamic: ephemeral if taken
47084 Control API (control) dynamic: ephemeral if taken
47085 cdp slot nothing listens: WebKitGTK has no DevTools Protocol, Hydrogen's frame bus does that job
8770 Hydrogen direct API 127.0.0.1 only
9001 Adom Bridge liveness beacon

Live values: ~/.config/hydrogen-desktop/ports.json on the host; GET <control>/ports or /ports/all.

Hostnames — reach the host at 127.0.0.1

From inside the workspace to the host

Use 127.0.0.1: it is the same interface on both sides. Every shell and code-server child also has ADOM_CARBON_URL / ADOM_HYDROGEN_URL (http://127.0.0.1:<proxy>), ADOM_HD_CONTROL_URL, and ADOM_SHARED_LOCALHOST=1.

The control port is dynamic per launch — read it from ~/.adom/hydrogen-control-url (your non-interactive Bash shells don't source .bashrc/profile.d, so the env var alone is unreliable): BASE="$(cat ~/.adom/hydrogen-control-url)".

From the host to workspace services

Directly at http://localhost:<port>/, since the network is shared. The code-server proxy is a fallback:

http://127.0.0.1:7380/proxy/<port>/      ws://127.0.0.1:7380/proxy/<port>/

Works for any workspace listener. Hydrogen answers a /proxy/<port>/ URL handed to it with a hint to use http://localhost:<port>/ instead: the direct form survives editor reloads and keeps absolute asset paths working.

From the host → host-side services

http://127.0.0.1:{port}/

Control API → http://127.0.0.1:47084/health

Relay

adom-bridge serve runs inside the workspace on 8765 (WS) / 8766 (HTTP); its live ports are in ~/.adom/cli-relay-ports.json. Hydrogen installs and starts Adom Bridge on Linux when a Linux build is published for the user's account, and hands it the relay URL and session.

VSCODE_PROXY_URI

Inside the workspace, VSCODE_PROXY_URI is set by code-server:

https://<slug>.adom.cloud/proxy/{{port}}/     (cloud)
http://{{port}}.localhost:<proxy port>/       (Hydrogen local, 1.0.224+; the path form http://localhost:7380/proxy/<port>/ still works)

Tools that build proxy URLs should use VSCODE_PROXY_URI when available, falling back to http://127.0.0.1:{code_server}/proxy/{port}/.

Running a command in the workspace from the host

You are normally already inside. From a host terminal:

sudo machinectl shell adom@Adom-Workspace
# or the helper Hydrogen itself uses (allowed without a password for the user):
sudo -n /usr/libexec/adom-hydrogen/hydrogen-workspace -d Adom-Workspace -u adom -- <cmd>

NEVER Do These

  1. NEVER hardcode Hydrogen's ports in workspace code. Read ~/.adom/hydrogen-control-url or the ADOM_* variables.
  2. NEVER use host.docker.internal or a gateway IP. The host is 127.0.0.1.
  3. NEVER open the LAN protection (flush inet adom_hydrogen) without the user asking for a service to be reachable from other devices, and tell them what it exposes.
  4. NEVER assume a port is free because nothing in the workspace uses it: the host shares the port space.
  5. NEVER assume 8770 is Adom Bridge. It is Hydrogen's own direct API on Linux.