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-ports description: >- How ports reach the Linux host from the Hydrogen workspace: one shared localhost, the code-server /proxy// URL as a fallback, the Ports window, ports.json and how to discover Hydrogen's live ports. Use when asked why my server isn't reachable, how to expose a port, or what localhost:7380 is.
Hydrogen ports on Linux
The workspace (Adom-Workspace, a systemd-nspawn machine) shares the host's network namespace.
A service listening on 127.0.0.1:<port> inside the workspace IS localhost:<port> on the host.
There is nothing to forward, map or register. Every shell has ADOM_SHARED_LOCALHOST=1, and it is
always 1 on Linux.
Bind 127.0.0.1
| Bind address in the workspace | Reachable on this computer? | From the network? |
|---|---|---|
127.0.0.1:N |
yes, localhost:N |
no |
0.0.0.0:N |
yes, localhost:N |
no for Hydrogen's ports and workspace-owned listeners (Hydrogen's nft table drops new inbound connections) |
Bind 127.0.0.1 (most dev servers' default). The port space is shared with the host: if a host
program already holds N, the workspace server fails with "address in use", and the reverse.
The code-server proxy URL (fallback)
http://localhost:7380/proxy/N/ ws://localhost:7380/proxy/N/
Works for any workspace listener, but prefer http://localhost:N/: no code-server dependency,
absolute asset paths keep working. Hydrogen's own responses steer /proxy/N/ URLs to the direct
form.
Examples:
- Your dev server on port 5173 →
http://localhost:7380/proxy/5173/ - The relay HTTP server on port 8766 →
http://localhost:7380/proxy/8766/ - adom-vscode's API on port 8821 →
http://localhost:7380/proxy/8821/
The Ports window
Adom menu > Ports... (or GET <control>/ports/all, which is what it renders):
- This computer: Hydrogen's own listeners (Control, Proxy, Discovery, direct API 8770,
beacon 9001). The
cdprow reads down on purpose: WebKitGTK has no DevTools Protocol. - Workspace: every listener inside the machine, read live, each with a direct URL
(
http://localhost:N) and a proxy URL. A port held by a host program shows as "Program on this computer, outside the workspace".
Click a URL to open it through the Browser Picker.
Hydrogen's host ports
Stored in ~/.config/hydrogen-desktop/ports.json (PortConfig: code_server, proxy,
control, cdp, hostname).
Defaults (you can override via ports.json):
| Service | Default host port |
|---|---|
| code-server | 7380 |
| Discovery server | 47080 (then 48080, 49180, 50280) |
Reverse proxy (proxy) |
47083 |
Hydrogen control API (control) |
47084 |
cdp (unused on Linux: WebKitGTK has no DevTools Protocol) |
47085 |
On startup a taken proxy, control or cdp port is replaced by an OS-assigned ephemeral port,
saved to ports.json. code_server is never moved. So never assume 47084: discover it.
Discovering Hydrogen itself: the three-rung ladder
Because control/proxy/cdp can rebind to ephemeral ports, anything that
needs to FIND a running Hydrogen walks this ladder (static defaults are only
rung zero, never an assumption):
Local files (authoritative when present).
- Host:
~/.config/hydrogen-desktop/ports.json(written every launch). - Inside the workspace:
~/.adom/hydrogen-control-url(full live control URL) and~/.adom/hydrogen-ports.json(all four ports), both stamped by Hydrogen into the workspace. The relay's ports are in~/.adom/cli-relay-ports.json(8765 WS / 8766 HTTP). - No file reachable:
GET http://127.0.0.1:<c>/for c in 47080, 48080, 49180, 50280 (the discovery probe); the reply carriescontrol_url.
- Host:
Verify liveness AND identity. A port answering
/healthis not proof it is THIS install: a zombie from an uninstalled copy can still be serving (a real observed failure).GET /buildinforeturnsinstance_id,pid, andinstall_path; check they match what you expect before trusting a discovered port.Cloud KV (works even when local files are unreachable). On every launch, and every 4 hours after, Hydrogen publishes its live runtime identity to the Adom cloud KV (Carbon):
- Key:
hydrogen.runtime.<machine>(machine = the kernel hostname, lowercased, other characters as_). - Value: a JSON string:
{host, control, proxy, cdp, code_server, instance_id, pid, install_path, version, ts}. - Read it:
GET https://carbon.adom.inc/user(session token or API key auth) thenbody.hydrogen_preferences.settings["hydrogen.runtime.<machine>"]. - Freshness: compare
ts(unix seconds) to now; the heartbeat refreshes it every 4 hours, so atsolder than ~5 hours means that instance is probably gone. Always confirm by hitting/buildinfoon the advertised port and matchinginstance_id.
Adom Bridge publishes its container connection the same way (
bridge.container.<id>, legacydesktop.container.<id>until ab's rename ships). This is what lets a cloud container, another machine, or a fresh install find the user's running desktop apps without port scanning.- Key:
Inside vs outside — which URL to use
| From | To a service on port N | Use |
|---|---|---|
| Workspace | another workspace service | http://localhost:N |
| Workspace | a host program | http://127.0.0.1:N |
| Host browser or tool | a workspace service | http://localhost:N |
| Workspace | Hydrogen's control API | $(cat ~/.adom/hydrogen-control-url) |
Common problems
- "My dev server doesn't load." Check it listens:
curl -sI localhost:5173inside the workspace. If it does, it loads on the host at the same URL. If it does not start, look for "address in use": something on the host may hold the port. - "Another device on my network can't reach it." Expected: the workspace is kept off the LAN. Only change that if the user asks, and say what it exposes.
- "
localhost:7380shows nothing." code-server is down or restarting; seehydrogen-workspace-monitoringandGET <control>/workspace/health.
Related skills
hydrogen-networking: shared localhost, LAN protection, NEVER-do ruleshydrogen-port-watcher: why there is no port forwarding to set uphydrogen-browser-picker: what happens when you click a Ports URL
Bridge ports are dynamic
KiCad, Fusion 360, Puppeteer, and any 3rd-party bridges no longer have known fixed ports. When a bridge launches, adom-bridge picks an available port at runtime and registers it. To find a running bridge's current port, query adom-bridge:
adom-bridge status
# Look at desktop.apps.<bridge>.bridgePort
Or use the bridge directly via adom-bridge CLI — you don't need the port at all:
adom-bridge kicad_open_board '{"path":"..."}' # adom-bridge routes to the right port
adom-bridge pup_eval '{"js":"..."}'
This means old code or skill examples that hardcoded fixed bridge ports
(8771 / 8773 / 8851) are stale. Use the adom-bridge CLI or status lookup
instead.
These verbs reach a machine that runs Adom Bridge: this computer once Hydrogen has installed it (when a Linux build is published for the user's account), or one of the user's other machines through the Adom mesh.
---
name: hydrogen-ports
description: >-
How ports reach the Linux host from the Hydrogen workspace: one shared
localhost, the code-server /proxy/<port>/ URL as a fallback, the Ports window,
ports.json and how to discover Hydrogen's live ports. Use when asked why my
server isn't reachable, how to expose a port, or what localhost:7380 is.
---
# Hydrogen ports on Linux
The workspace (`Adom-Workspace`, a systemd-nspawn machine) shares the host's network namespace.
A service listening on `127.0.0.1:<port>` inside the workspace IS `localhost:<port>` on the host.
There is nothing to forward, map or register. Every shell has `ADOM_SHARED_LOCALHOST=1`, and it is
always 1 on Linux.
## Bind 127.0.0.1
| Bind address in the workspace | Reachable on this computer? | From the network? |
|---|---|---|
| `127.0.0.1:N` | yes, `localhost:N` | no |
| `0.0.0.0:N` | yes, `localhost:N` | no for Hydrogen's ports and workspace-owned listeners (Hydrogen's nft table drops new inbound connections) |
Bind `127.0.0.1` (most dev servers' default). The port space is shared with the host: if a host
program already holds N, the workspace server fails with "address in use", and the reverse.
## The code-server proxy URL (fallback)
```
http://localhost:7380/proxy/N/ ws://localhost:7380/proxy/N/
```
Works for any workspace listener, but prefer `http://localhost:N/`: no code-server dependency,
absolute asset paths keep working. Hydrogen's own responses steer `/proxy/N/` URLs to the direct
form.
Examples:
- Your dev server on port 5173 → `http://localhost:7380/proxy/5173/`
- The relay HTTP server on port 8766 → `http://localhost:7380/proxy/8766/`
- adom-vscode's API on port 8821 → `http://localhost:7380/proxy/8821/`
## The Ports window
Adom menu > **Ports...** (or `GET <control>/ports/all`, which is what it renders):
- **This computer:** Hydrogen's own listeners (Control, Proxy, Discovery, direct API 8770,
beacon 9001). The `cdp` row reads down on purpose: WebKitGTK has no DevTools Protocol.
- **Workspace:** every listener inside the machine, read live, each with a direct URL
(`http://localhost:N`) and a proxy URL. A port held by a host program shows as "Program on this
computer, outside the workspace".
Click a URL to open it through the Browser Picker.
## Hydrogen's host ports
Stored in `~/.config/hydrogen-desktop/ports.json` (`PortConfig`: `code_server`, `proxy`,
`control`, `cdp`, `hostname`).
Defaults (you can override via ports.json):
| Service | Default host port |
|---------|-------------------|
| code-server | 7380 |
| Discovery server | 47080 (then 48080, 49180, 50280) |
| Reverse proxy (`proxy`) | 47083 |
| Hydrogen control API (`control`) | 47084 |
| `cdp` (unused on Linux: WebKitGTK has no DevTools Protocol) | 47085 |
On startup a taken `proxy`, `control` or `cdp` port is replaced by an OS-assigned ephemeral port,
saved to ports.json. `code_server` is never moved. So never assume 47084: discover it.
## Discovering Hydrogen itself: the three-rung ladder
Because `control`/`proxy`/`cdp` can rebind to ephemeral ports, anything that
needs to FIND a running Hydrogen walks this ladder (static defaults are only
rung zero, never an assumption):
1. **Local files (authoritative when present).**
- Host: `~/.config/hydrogen-desktop/ports.json` (written every launch).
- Inside the workspace: `~/.adom/hydrogen-control-url` (full live control URL)
and `~/.adom/hydrogen-ports.json` (all four ports), both stamped by
Hydrogen into the workspace. The relay's ports are in
`~/.adom/cli-relay-ports.json` (8765 WS / 8766 HTTP).
- No file reachable: `GET http://127.0.0.1:<c>/` for c in 47080, 48080, 49180, 50280
(the discovery probe); the reply carries `control_url`.
2. **Verify liveness AND identity.** A port answering `/health` is not proof
it is THIS install: a zombie from an uninstalled copy can still be serving
(a real observed failure). `GET /buildinfo` returns `instance_id`, `pid`,
and `install_path`; check they match what you expect before trusting a
discovered port.
3. **Cloud KV (works even when local files are unreachable).** On every
launch, and every 4 hours after, Hydrogen publishes its live runtime
identity to the Adom cloud KV (Carbon):
- Key: `hydrogen.runtime.<machine>` (machine = the kernel hostname,
lowercased, other characters as `_`).
- Value: a JSON string:
`{host, control, proxy, cdp, code_server, instance_id, pid, install_path, version, ts}`.
- Read it: `GET https://carbon.adom.inc/user` (session token or API key
auth) then `body.hydrogen_preferences.settings["hydrogen.runtime.<machine>"]`.
- Freshness: compare `ts` (unix seconds) to now; the heartbeat refreshes it
every 4 hours, so a `ts` older than ~5 hours means that instance is
probably gone. Always confirm by hitting `/buildinfo` on the advertised
port and matching `instance_id`.
Adom Bridge publishes its container connection the same way
(`bridge.container.<id>`, legacy `desktop.container.<id>` until ab's rename ships). This is what lets a cloud container, another
machine, or a fresh install find the user's running desktop apps without
port scanning.
## Inside vs outside — which URL to use
| From | To a service on port N | Use |
|---|---|---|
| Workspace | another workspace service | `http://localhost:N` |
| Workspace | a host program | `http://127.0.0.1:N` |
| Host browser or tool | a workspace service | `http://localhost:N` |
| Workspace | Hydrogen's control API | `$(cat ~/.adom/hydrogen-control-url)` |
## Common problems
- **"My dev server doesn't load."** Check it listens: `curl -sI localhost:5173` inside the
workspace. If it does, it loads on the host at the same URL. If it does not start, look for
"address in use": something on the host may hold the port.
- **"Another device on my network can't reach it."** Expected: the workspace is kept off the LAN.
Only change that if the user asks, and say what it exposes.
- **"`localhost:7380` shows nothing."** code-server is down or restarting; see
`hydrogen-workspace-monitoring` and `GET <control>/workspace/health`.
## Related skills
- `hydrogen-networking`: shared localhost, LAN protection, NEVER-do rules
- `hydrogen-port-watcher`: why there is no port forwarding to set up
- `hydrogen-browser-picker`: what happens when you click a Ports URL
## Bridge ports are dynamic
KiCad, Fusion 360, Puppeteer, and any 3rd-party bridges no longer have known
fixed ports. When a bridge launches, **adom-bridge picks an available port at
runtime** and registers it. To find a running bridge's current port, query
adom-bridge:
```bash
adom-bridge status
# Look at desktop.apps.<bridge>.bridgePort
```
Or use the bridge directly via adom-bridge CLI — you don't need the port at all:
```bash
adom-bridge kicad_open_board '{"path":"..."}' # adom-bridge routes to the right port
adom-bridge pup_eval '{"js":"..."}'
```
This means **old code or skill examples that hardcoded fixed bridge ports
(8771 / 8773 / 8851) are stale.** Use the adom-bridge CLI or `status` lookup
instead.
These verbs reach a machine that runs Adom Bridge: this computer once Hydrogen has installed it
(when a Linux build is published for the user's account), or one of the user's other machines
through the Adom mesh.