main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-port-watcher description: >- Why you don't need port forwarding in Hydrogen on Linux: the workspace shares the host's network, so every port it binds, including 127.0.0.1 OAuth callbacks, is already on the host's localhost. Use when asked about port forwarding, OAuth callback ports, Codex or extension auth, or why can't I reach my port.

Hydrogen port watcher on Linux: there is nothing to forward

TL;DR for the AI: do NOT set up port forwarding. The Adom-Workspace machine runs in the host's network namespace, so a listener on 127.0.0.1:<port> in the workspace is the host's localhost:<port> already. If a port is not reachable, the service did not bind (or failed with "address in use" because a host program holds the port). Check with ss -ltnp in the workspace.

OAuth callbacks just work

VS Code extensions (Codex, Claude Code, Copilot, GitLens) start a callback server on 127.0.0.1:<port> in the workspace and open the provider's page in the user's browser. The browser's redirect to http://localhost:<port>/callback?... lands on that server directly. No watcher, no host proxy, no registration. On Linux, AI sign-ins from Manage AIs open straight in the system browser (no in-app tab, no picker).

The forwarding machinery still in the API (not needed here)

Hydrogen keeps its port-forward registry for parity, but on a shared network it has nothing to do: a "host proxy" would have to bind the very port the workspace service already holds, so it fails to bind (logged as [port-fwd] Failed to bind host port).

  • POST <control>/adom-port-hints with {"port":N,"action":"register","name":"...","reason":"..."} (also unregister, open, close); GET <control>/adom-port-hints lists entries.
  • POST <control>/start-oauth-proxy {"port":N} or {"url":"<oauth url with redirect_uri>"}.

Do not call these to "fix" reachability on Linux. If a page in the browser shows Hydrogen's "OAuth callback proxy" 502, something called them anyway; the real callback server is reachable at localhost:<port> without it.

Debugging an unreachable port

ss -ltnp | grep ':<port>'          # who listens (host listeners show here too)
curl -sI http://127.0.0.1:<port>/  # same answer inside the workspace and on the host
  • Nothing listening: the service never started or already exited (a callback server closes after one request).
  • Listening but owned by a host program: the workspace server could not bind the same port; pick another port.
  • Reachable here but not from another device: expected, Hydrogen's nft table keeps the workspace off the LAN (see hydrogen-networking).
  • hydrogen-networking: shared localhost, LAN protection
  • hydrogen-ports: the Ports window, ports.json, discovering Hydrogen's live ports