Adom Hydrogen

@@ -132,6 +132,7 @@ Hover a card and dwell, and it zooms to a full billboard so you can actually rea | [The Dock Bar](docs/dockbar.md) | The full tour with screenshots of everything the Dock Bar does (the interstitial, webview takeover, container launch steps, AI threads new and resumed, health LEDs, honest failures, settings), plus the complete `dockbar.json` manifest reference and the publisher checklist for making YOUR app dock-ready. | | [Project workspaces](project-workspaces/README.md) | The layout a project ships (hydrogen/workspace.json): the menu next to the Adom logo, Apply, Unload and Save as project workspace, the one-time offer, placeholder tabs that know the Adom Bridge state, and every control on the API so your AI never needs a mouse. Opens with a 70-second video. | | [Setup steps pitfalls](setup-steps-pitfalls/README.md) | Everything we know can go wrong while Hydrogen sets itself up (84 pitfalls, by setup phase): what you see, what Hydrogen does about it, and recorded videos of the big ones: installing WSL2 from scratch, Windows 10, a PC without hardware virtualization, a nearly full drive, and WSL networking. Each reproducible pitfall has a test that runs on every build. |+| [NAT vs mirrored networking](nat-vs-mirrored/README.md) | A narrated 4-minute video: Claude Code, Codex, Antigravity and Kimi Code signing in on both WSL networking modes, an app dashboard on NAT, and the setup step that switches modes on its own. Why mirrored broke installs on some PCs and how Hydrogen balances the two. | | [What's new in 1.0.701](releases/2026-11-01/README.md) | Everything since 1.0.666, the last public release: setup that finishes on more PCs (mirrored to NAT switch, honest NAT sign-in), workspace networking in Settings, a WSL watchdog, links that remember your browser, a lighter Hydrogen in the background, the editor keeping your folder, every permission to every frame, and Codex that can no longer freeze the editor. | | [What's new, 12 to 14 September 2026](releases/2026-09-14/README.md) | The weekend tour with pictures: Hydrogen Widgets, Project workspaces, Report a problem, layout persistence, the honest workspace meter, Recovery, the bell, Annotate, and the versions that carry them. | | [Hydrogen Widgets](widgets/README.md) | Small live panels in the Title Bar, served from your workspace: Claude usage (5-hour, weekly, model bucket), Codex usage, a clock to copy. Any wiki repo can ship one with a hydrogen-widget.json; open widgets come back after a restart; everything is on the control API. |

@@ -0,0 +1,63 @@+# NAT vs mirrored networking++<video controls preload="metadata" width="1080" poster="nat-vs-mirrored/nat-vs-mirrored-poster.jpg" src="nat-vs-mirrored/nat-vs-mirrored.mp4" style="max-width:100%;height:auto"></video>++*Four minutes, narrated. Claude Code, Codex, Antigravity and Kimi Code each sign out and back in on mirrored networking, then again on NAT. An app dashboard runs on NAT, and you see the setup step that switches modes on its own. Recorded on a test PC running Hydrogen 1.0.701. The waiting is sped up (the corner shows how much), and email addresses are blurred. [Download the video](nat-vs-mirrored/nat-vs-mirrored.mp4).*++Hydrogen runs your Linux workspace in WSL on your own Windows PC. WSL can connect that workspace to Windows in two ways, and which one works depends on the PC. This page covers both modes, the install problem the difference caused, and how Hydrogen handles each mode now.++## The two modes++| | Mirrored (the default) | NAT |+|---|---|---|+| How it works | Linux shares Windows' network. `localhost` on Windows and `localhost` in Linux are the same place. | Linux gets its own small network behind Windows. WSL forwards Windows' `localhost` into it. |+| AI sign-ins | The browser on Windows calls the AI's listener in the workspace directly. | Same, through WSL's localhost forwarding. Hydrogen checks the trip before relying on it. |+| App dashboards | Open at the same address in both modes (below). | Same. |+| Where it breaks | Some PCs block it: a security tool or a firewall policy stops Windows from reaching the workspace. | Turning off `localhostForwarding` in `.wslconfig` breaks it. Hydrogen turns it back on. A Windows program can also already hold an app's port. |++## Why this became an install problem++On the PCs where mirrored is blocked, setup used to stop with a message that pointed the wrong way:++- **The editor never loaded** at "Sign in to Adom, then activate the editor", and setup halted there ([#145](https://wiki.adom.inc/adom/hydrogen/issues/145)).+- **Windows could not reach a workspace that was running fine**, and setup ended on "Couldn't build the workspace image". That sent people off to delete a good workspace ([#157](https://wiki.adom.inc/adom/hydrogen/issues/157)).++Both people who reported it had a working workspace that Windows could not reach. Install data showed the same pattern: setup halted at the editor step or the workspace step, and those people never got to use Hydrogen.++## How Hydrogen handles it now++**During install.** The editor step signs you in to Adom and then checks that the editor really loaded. If it does not load on mirrored, or Windows cannot reach the workspace, setup:++1. switches this PC to NAT once, recording your original setting so uninstalling puts it back,+2. restarts WSL (unless another Linux distribution is running, in which case it stops and names it), and+3. carries on.++A second failure in the same run stops and says why, so it never loops. Turning IPv6 back on from the setup card also puts you back on mirrored. (1.0.682, 1.0.686, 1.0.689)++**Sign-ins on NAT.** Hydrogen used to warn on every NAT workspace that AI sign-ins could not work. That was wrong, because WSL forwards Windows' `localhost` into the workspace. Now Hydrogen tests the real trip: it opens a one-off listener in the workspace and fetches it from Windows. It warns only when that fails, and then points you to signing in with an API key. When you click Sign in, Your AIs also checks that the AI's own callback port answers from Windows. If `.wslconfig` has `localhostForwarding` turned off, setup turns it back on and remembers your value. (1.0.671, 1.0.672)++How each AI signs in:++| AI | How sign-in finishes | NAT |+|---|---|---|+| Claude Code | Browser calls back to a localhost port in the workspace | Works through forwarding, port checked first |+| Codex | Browser calls back to localhost:1455 | Works through forwarding, port checked first |+| Antigravity | Google sign-in, handed back to the workspace | Works |+| Kimi Code | Device code: you approve in the browser, nothing calls back | Works, nothing to forward |++**App dashboards.** Hydrogen opens dock apps and apps your AI builds through its own proxy at an address like `http://8893.localhost:47083/`, or straight at the app's `127.0.0.1` port. Either way the address is the same in both modes, so nothing changes when you switch. On NAT, a program on Windows can already hold the port an app wants. The webview tab now names that program and asks your AI to use another port, instead of quietly showing the other program's page. (1.0.695)++**Your choice, any time.** **Settings, Workspace networking** switches between mirrored and NAT. WSL restarts and the editor reconnects on its own. (1.0.675)++## The balance++- **Mirrored by default**: it is the simplest, and everything connects directly.+- **NAT automatically**, only on the PCs where mirrored is blocked, with nothing for you to diagnose.+- **One setting** to switch either way, which Hydrogen puts back if you uninstall.++## Known rough edges (from making this video)++- **The editor can take up to a minute to answer after a switch.** Your AIs says "Your workspace is still starting" in the meantime. Once, after switching to NAT, it stayed stuck until the editor was reloaded. That is on the list for the next build.+- **Windows may ask a firewall question for Adom Hydrogen** the first time a sign-in runs on NAT. In the recording, the sign-in finished after pressing Cancel, and Windows did not ask again. Stopping Hydrogen from triggering the prompt at all is on the list.++Each behaviour above has a check in Hydrogen's promotion gate (`mirrored-breaks-editor-nat`, `mirrored-unreachable-workspace-nat`, `wsl-nat-fallback`, `nat-signin-honest` and `nat-ai-app-webview`), and every build is tested against it before it goes public.

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯