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

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.