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-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-Workspacemachine runs in the host's network namespace, so a listener on127.0.0.1:<port>in the workspace is the host'slocalhost:<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 withss -ltnpin 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-hintswith{"port":N,"action":"register","name":"...","reason":"..."}(alsounregister,open,close);GET <control>/adom-port-hintslists 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).
Related skills
hydrogen-networking: shared localhost, LAN protectionhydrogen-ports: the Ports window, ports.json, discovering Hydrogen's live ports
---
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
```bash
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`).
## Related skills
- `hydrogen-networking`: shared localhost, LAN protection
- `hydrogen-ports`: the Ports window, ports.json, discovering Hydrogen's live ports