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-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.1is 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 -ltnor/proc/net/tcpinside the workspace also lists the host's listeners. Hydrogen's Ports window tells them apart by cgroup: processes inmachine.sliceare 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
- NEVER hardcode Hydrogen's ports in workspace code. Read
~/.adom/hydrogen-control-urlor theADOM_*variables. - NEVER use
host.docker.internalor a gateway IP. The host is127.0.0.1. - 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. - NEVER assume a port is free because nothing in the workspace uses it: the host shares the port space.
- NEVER assume 8770 is Adom Bridge. It is Hydrogen's own direct API on Linux.
---
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:
```bash
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.