app
Adom Hydrogen
Public Made by Adomby adom
The whole Adom experience as one signed native app: your editor, your AI agent, and the full electronics design toolchain, running locally on your own machine.
master
Setup steps pitfalls
Everything we know can go wrong while Hydrogen sets itself up on a Windows PC, what the person in front of the screen sees when it does, and what Hydrogen does about it. Each pitfall is a real report from a user or a test box, and the ones we can reproduce have a scenario script that runs against every build before it ships, so a fix stays fixed.
If you hit something during setup that is not on this page, please use Report this problem on the setup card. It's early days for Adom and unusual setups are exactly what we need to hear about; we try to fix reported problems within 2 hours.
How setup works, in one paragraph
Hydrogen runs a Linux workspace (a WSL2 distro called Adom-Workspace) on your PC and puts a code editor and your AIs inside it. Setup does, in order: make sure WSL2 is on (installing it, with one Windows restart, if it is not), download and import the workspace image, connect the workspace to Windows (WSL's mirrored networking, so both share one localhost), start the editor, connect Adom Bridge (the link to your desktop apps), and finally check every piece for real before it calls itself done. Signing in to your AIs happens after setup, in the Choose your AI dialog.
Recorded scenarios
Each video was recorded on a test PC with the build named in its caption, sped up where nothing is happening, with captions on every step.
| Scenario | What it shows | Video | Regression script |
|---|---|---|---|
| WSL2 installed from scratch | A PC that has never had WSL2: Hydrogen turns it on, asks for one restart, and finishes setup by itself afterwards | video | hd-vm-test.sh (fresh snapshot) |
| Mirrored networking: first install and an advanced user's own choice | Hydrogen connects the workspace to Windows without asking; a user who deliberately set NAT keeps it, and the Your AIs dialog explains what that costs | video | scripts/test-scenarios/wslconfig-mirrored.sh |
| WSL's firewall blocks the workspace | A security tool or policy blocked WSL's network; Hydrogen allows exactly outbound and loopback with one admin prompt and finishes | video | scripts/test-scenarios/wsl-network-blocked.sh |
| Windows 10 | The installer stops right away with a clear message, before installing anything | video | installer gate (manual run on an Azure Windows 10 VM) |
| No hardware virtualization | A PC that cannot run WSL2: what it saw on 1.0.554 (installed WSL2, restarted, then hid the explanation behind other windows) and what 1.0.555 changes | video | manual run on an Azure VM with the hypervisor off |
| Not enough disk space | With 0.8 GB free the import filled the drive, setup sat silent for ten minutes, then asked for a Windows restart; 1.0.556 checks for 8 GB first and stops in a second (verified on winvm); Adom Bridge's approval box covered that message, fixed for 1.0.557 | video | scripts/test-scenarios/disk-almost-full.sh |
| Expired Adom sign-in | The saved session is rejected; Hydrogen clears it and opens a fresh sign-in while setup carries on | video | scripts/test-scenarios/dead-session.sh |
| Another WSL distro already running | Hydrogen never stops it on its own; when it needs one WSL restart it names the distro and lets you choose (1.0.559) | video | scripts/test-scenarios/other-distro-running.sh |
| Workspace download blocked | Setup stops in seconds and says your network is blocking Adom's download server (1.0.557) | video | scripts/test-scenarios/image-download-blocked.sh |
| Another app holding the editor's port | A Windows app on 127.0.0.1:7380: from a generic error, to wrong advice, to naming the app in 20 seconds (1.0.560) | video | scripts/test-scenarios/port-7380-taken.sh |
| Damaged workspace image | Hydrogen notices the bad copy, fetches a fresh one and finishes (1.0.562) | video | scripts/test-scenarios/download-cache.sh corrupt |
| Download cut short | Hydrogen resumes from where it stopped and finishes (1.0.562) | video | scripts/test-scenarios/download-cache.sh resume |
| Sign-in window closed, or its link expired | Hydrogen brings the sign-in back, and after expiry opens a fresh link (1.0.565) | video | scripts/test-scenarios/signin-window.sh |
| Workspace deleted after setup finished | Before 1.0.565 the editor waited forever; now Hydrogen notices at launch and rebuilds it | video | scripts/test-scenarios/state-recovery.sh gone |
WSL2 from scratch, recorded on 1.0.554 on a clean Windows 11 PC with no WSL2. About 10 minutes of setup work: the installer, turning on WSL2 (about 30 seconds), one restart that waits for the user's click, then Hydrogen resumes by itself, builds the workspace and asks for the Adom sign-in. The frames where the tester typed their account details are replaced by a card.
A PC that cannot run WSL2 (an Azure VM with the Windows hypervisor turned off), on 1.0.554. Captions say what 1.0.555 changes.
Not enough disk space (0.8 GB free on C:), on 1.0.554. Fixed in 1.0.556.
Windows 10 22H2: the installer stops before installing anything.
Mirrored networking, recorded on 1.0.552: first install turns it on with no question, the original setting is saved for uninstall, a user who sets NAT is respected, and the Your AIs dialog warns about AI sign-in. (On 1.0.554 and later the setup card no longer shows a warning at all; the Your AIs dialog is the only place it appears.)
WSL's firewall blocks the workspace, recorded on 1.0.554: Hydrogen finds outbound and loopback blocked, allows exactly those two with one admin prompt (this test PC has UAC off, so the prompt does not show), and setup finishes on its own.
Expired Adom sign-in, recorded on 1.0.559: Hydrogen clears the dead session and opens a fresh sign-in; setup carries on.
Another WSL distro running, 1.0.556 then 1.0.560: Hydrogen never stops it on its own; it explains the one restart it needs, lets you choose, and the button finishes setup (pressed and verified on 1.0.560).
Workspace download blocked, 1.0.556 then 1.0.559: from the wrong advice to a plain explanation.
Another app on the editor's port, 1.0.556, 1.0.559 and 1.0.560: Hydrogen now asks Windows who is listening and names the app.
A damaged workspace image, recorded on 1.0.562: the fingerprint check catches it and setup quietly downloads a fresh copy.
A download cut short, recorded on 1.0.562: setup resumes from 250 MB instead of starting over.
The Adom sign-in closed and then expired, recorded on 1.0.565: Hydrogen brings it back, and after the link expires it opens a fresh one.
The workspace deleted after setup finished, 1.0.564 then 1.0.565: from stuck forever to a rebuild in about a minute and a half.
The pitfalls, by setup phase
Tested by names the scenario script that reproduces it on a test PC. Not yet means it is documented here and handled in the code, but has no automated reproduction yet.
Before WSL2 is involved
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| ARM64 PC (Surface Pro X and similar) | Setup stops: "This PC's processor is ARM64; Hydrogen needs an x64 PC" | Stops before the 800 MB download; nothing else is changed | Not yet (adom/hydrogen#89) |
| Setup started twice at once | Nothing: setup runs once | A lock makes the second start a no-op: seen live on winvm (2026-10-07), two starts 0.6 seconds apart logged "already running, ignoring duplicate invocation" and setup completed normally | Seen live on winvm |
Saved progress says done but the workspace is gone (an uninstall and reinstall, wsl --unregister, a cleanup tool) |
1.0.565: setup runs again by itself and the workspace is back in about 95 seconds (was, on 1.0.564: "Your workspace is ready" next to an editor stuck on "Starting AI Environment..." forever) | At launch it checks that the workspace really exists (an instant registry read) and rebuilds it if it does not | state-recovery.sh gone, video |
| Workspace there but the editor died with an old Hydrogen | Editor stuck on "Starting" | Re-runs the workspace and editor steps | Not yet |
| A step left "running" by a crash | Nothing: setup carries on | Re-runs the step on the next launch and finishes (verified on 1.0.565: done in 67 seconds) | state-recovery.sh stuck |
| A minute of silence on a cold PC | (was) a dead panel | Reads Windows' registry instead of waking WSL, and narrates | Not yet |
| A console window flashes during install | A black terminal pops up | Every helper runs hidden | Not yet |
| An old Adom Bridge from a previous install still running | Setup talks to a leftover | Reclaims stale processes; the uninstaller cleans up | Not yet |
Turning on WSL2 (and the one restart)
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| WSL2 is not installed | The card explains, one Windows permission prompt, then Restart now / Restart later | Installs WSL2 itself, shows the download and Windows' own progress, never restarts without your click, and resumes setup after the restart | hd-vm-test.sh |
| You click No on the permission prompt (or miss it over remote desktop) | "One quick permission to turn on WSL2" with a button to ask again | Waits for you; the button asks again | Not yet |
| GitHub is blocked on your network | "Couldn't download WSL2: this PC can't reach github.com" | Names the network problem instead of blaming your Windows edition | Not yet |
| WSL2 still missing after the install and restart | Manual steps for an admin PowerShell | Stops instead of restarting in a loop | Not yet |
| No hardware virtualization (BIOS setting off, an older or locked-down laptop, or a virtual machine without nested virtualization) | "This PC can't run Hydrogen's workspace yet", two sentences, and a How to turn on virtualization button that opens Microsoft's how-to in front (verified on 1.0.560, including a 1024x768 screen) | Checks before installing WSL2 when Windows can tell (no hypervisor running and virtualization off in firmware); otherwise stops at the first workspace build with the same message, and brings the card to the front | video |
| Windows 10, or Windows 11 before 22H2 | The installer says "Adom Hydrogen needs Windows 11, version 22H2 or newer" with the PC's version and build | Stops before installing anything. Before 1.0.555 the gate let Windows 11 21H2 through (build 22000), which then failed in setup, and named the wrong reason | video |
| Restart later | Setup waits; a gentle reminder every few minutes | Never forces a restart; finishes after whatever restart you choose | Not yet |
| Edge says "Restore pages: Microsoft Edge closed unexpectedly" after the restart | A bubble over the Adom sign-in page | Nothing yet: the restart closed Edge, and Edge offers to restore it. Harmless, but confusing at the one moment we need the user | hd-vm-test.sh (seen 2026-10-06) |
| Windows asks "Allow important notifications from Adom Bridge?" | A Windows prompt about an app the user has never heard of, on top of the sign-in (Seen on test PCs signed in to an account whose Adom Bridge is linked to other machines, which mirror their alerts in; still to confirm on a single-PC account.) | Nothing yet: Adom Bridge asks for that permission on its first start, which lands during setup. To fix: ask later, after setup | hd-vm-test.sh (seen 2026-10-06) |
| Edge's own first-run welcome takes over the screen | A brand-new PC: the first thing that opens Edge (the Adom sign-in) gets "Welcome to Microsoft Edge" first | Nothing yet; the user clicks through Edge's welcome. Seen on a fresh Windows 11 VM, 2026-10-06 | Not yet |
| Hydrogen's message hidden behind other windows when setup stops | (was) the Adom sign-in in Edge and Adom Bridge's red activity log on top, Hydrogen's explanation found last (Seen on test PCs signed in to an account whose Adom Bridge is linked to other machines, which mirror their alerts in; still to confirm on a single-PC account.) | 1.0.555 brings the setup card to the front when setup stops (only then) | video |
| Windows Defender flags an unsigned helper as a trojan | The program disappears | Hydrogen and Adom Bridge are code-signed; on a Windows 10 test PC Defender's machine-learning check quarantined our own unsigned test robot (Trojan:Win32/Bearfoos.B!ml), not anything we ship |
Seen on a test PC, 2026-10-06 |
| Windows' "You're almost done setting up your PC" page after the restart | (was) that page covered Hydrogen | Turns those pages off before the restart | Not yet |
| The "Welcome to WSL" window pops over Hydrogen | A stray WSL window | Minimizes it | hd-vm-test.sh |
| WSL is wedged before the install | A heartbeat, then a gentle restart countdown | Clears stuck WSL processes, asks for a restart at most twice, then gives manual steps | Not yet |
Building the workspace
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| Slow download of the workspace image | Progress with size, speed and time left | Starts the download early (it overlaps the WSL restart) and resumes after an interruption | Not yet |
| Download cut short (restart, crash, network drop) | Nothing alarming: setup keeps building | Resumes from where it stopped and checks the finished file (verified on 1.0.562: resumed from 250 MB) | download-cache.sh resume, video |
| Corrupt download, or a damaged cached image | Nothing alarming: setup keeps building | The SHA-256 check catches it, deletes the copy and downloads a fresh one without stopping (verified on 1.0.562) | download-cache.sh corrupt, video |
| The workspace download is blocked (company network, VPN, proxy, security tool) | 1.0.557+: "Hydrogen couldn't download your workspace. Your PC could not reach Adom's download server..." (was, on 1.0.556: "open PowerShell and run wsl --unregister", the wrong fix) | Stops within seconds, no hang, no crash; Run setup again resumes once the network allows it | image-download-blocked.sh, video |
| Not enough disk space | 1.0.556: "Your C: drive is almost full (N GB free). Hydrogen's workspace needs about 8 GB..." before anything is built | Checks before building; if a drive fills anyway, the four-minute no-progress watchdog says the drive is full instead of asking for a Windows restart (which it did before) | disk-almost-full.sh, video |
| A workspace left half-registered by a crash | (was) every import failed | Removes only Hydrogen's own leftover and imports again | Not yet |
| Another WSL command during the workspace's first boot | (was) a permanently broken workspace | One WSL command at a time while it boots | Not yet |
| The workspace never finishes booting | "WSL2 looks wedged: run wsl --shutdown, then Run setup again" | Stops with the exact fix | Not yet |
| WSL's management service throws "Catastrophic failure" | Retries, then the fix | Retries with backoff, never shuts down your other WSL distros | HD_TEST_WSL_FAIL test hook |
| Other WSL distros running (Docker Desktop, your own Ubuntu) while a setting needs a WSL restart | 1.0.559: "Hydrogen needs to restart WSL once. Another Linux distribution is running (name)... Restarting WSL stops name too: save your work there, then restart." with a Restart WSL and finish setup button (was: "This usually clears up on its own: run setup again", which never could, verified on 1.0.556) | Never stops your distros on its own; the restart happens only when you press the button, then setup finishes (verified on 1.0.560) | other-distro-running.sh (adom/hydrogen#85), video |
| A busy workspace mistaken for a broken disk | (was) a WSL restart, then a request to restart Windows on a healthy PC | Waits for a real answer; only a real disk failure counts | Not yet (found on a test PC, 2026-10-06) |
| A busy workspace mistaken for a missing editor | (was) the editor reinstalled from scratch | Only reinstalls on a real "not installed" | Not yet (found on a test PC, 2026-10-06) |
Connecting the workspace to Windows (networking)
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| WSL's default networking (NAT) | "Connecting your workspace to Windows" | Turns on mirrored networking, saves your original setting, and puts it back if you uninstall | wslconfig-mirrored.sh |
| You deliberately set another networking mode | Nothing during setup; the Your AIs dialog warns that AI sign-in needs mirrored networking, with a button to turn it back on | Respects your choice and never changes it back on its own | wslconfig-mirrored.sh (adom/hydrogen#100) |
| A security tool or policy set WSL's firewall to block it | (was) setup stopped at "Building your workspace" | One WSL restart, then one admin prompt that allows exactly outbound traffic and loopback; inbound stays blocked | wsl-network-blocked.sh (adom/hydrogen#100), video |
| The network comes back slowly after that fix | (was) "not confirmed", and Try again worked a minute later | Waits up to 90 seconds for the network, then carries on | wsl-network-blocked.sh |
| Your organization's policy overrides the firewall | "A policy managed by your organization may be overriding it" | Says so and carries on | Not yet |
| Windows too old for mirrored networking (before Windows 11 22H2) | The installer stops (see Windows 10 above) | Since 1.0.555 the installer's own minimum is 22H2, so setup never meets this | video |
| A full-tunnel VPN | Windows is online but the workspace is not | Names the VPN adapter after setup | Not yet (adom/hydrogen#77) |
| A Windows proxy leaking into WSL | (was) a false "port taken" error | Checks from Windows first, bypassing the proxy | Not yet (adom/hydrogen#89) |
Starting the editor
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| Windows can't reach the editor | "Windows could not reach the workspace: a VPN, security tool or firewall" | Three repair rounds, then the network fix, then a clear diagnosis | wsl-network-blocked.sh |
| Port 7380 already taken by a Windows app | 1.0.560: "Another app is using Hydrogen's editor port. Port 7380 is in use by app name on Windows, and Hydrogen's editor needs it. Close app name, then run setup again." within about 20 seconds (was: the generic "Setup didn't finish" on 1.0.556; on 1.0.559 the stranger fooled an early check, the editor pane loaded it, and the card said "run wsl --unregister") | Asks Windows which app is listening before trusting the port, at every step that checks it, and stops without retrying | port-7380-taken.sh, video |
| The editor listening on your whole network | (was) a passwordless editor visible on your Wi-Fi | Listens on this PC only, and moves older installs over at launch | ralph codeserver.localhost_only (adom/hydrogen#100) |
| The editor waits for your Adom sign-in | "Waiting for you to finish signing in to Adom" | Waits as long as you need | hd-vm-test.sh |
| The editor's extension never starts | "The editor didn't finish starting" | Run setup again restarts it | Not yet |
Signing in
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| You close the Adom sign-in window | The sign-in comes back within seconds, and the card offers "Open the sign-in" | Reopens it by itself, then shows a button (verified on 1.0.565) | signin-window.sh, video |
| The sign-in link expires (about 15 minutes) | "Open the sign-in" opens a fresh link | Never reopens a dead link: after 16 minutes the button opened a brand new one (verified on 1.0.565) | signin-window.sh, video (adom/hydrogen#39) |
| You sign in hours later | Setup waits | No deadline; carries on when you sign in | Not yet |
| A saved sign-in from an old install has expired | The Adom sign-in page opens with one Approve button (verified on 1.0.559; was: stuck 6 minutes at "Opening your editor") | Checks the saved sign-in with Adom at launch; if it is dead, clears it and asks you to sign in fresh while the workspace keeps building | dead-session.sh, video |
| The sign-in opens in Edge instead of your browser | (was) the wrong browser | Opens your default browser | Not yet |
Adom Bridge (your desktop apps)
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| Adom Bridge can't be installed (no network) | A note that Hydrogen will retry on its next launch | Carries on; it is not needed to finish setup | Not yet |
| Adom Bridge slow to start | A note; it keeps trying | Carries on | Not yet |
| The connection to your desktop apps doesn't start | "Adom Bridge isn't connected yet: run setup again" | Run setup again restarts it | Not yet |
| Adom Bridge's approval box covers Hydrogen when setup stops early | (was) "Permission requests: The cloud AI wants to run shell / system commands on this machine" on top of Hydrogen's explanation, for a request nobody was waiting on | 1.0.557 asks Adom Bridge for that approval only after the workspace is built, so a stop during the build never raises it (adom-bridge#228 for withdrawing a pending box) | disk-almost-full.sh, video |
The final check and the setup card
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| A check fails at the very end | A title that names the problem, one sentence on what to do, and one button that says what it does (for example Run setup again, or Reconnect and finish setup) | Every failure has a plain explanation; Continue anyway skips ahead; Report this problem sends us the log | Any scenario that stops |
| (was) the card quoted a log line and offered Try again / Open Hydrogen / Report side by side | Replaced on 1.0.554 | ||
| The setup card reloads after setup stopped (WebView2 can do this on its own) | 1.0.564: the stop message and its buttons are still there (was: the card went back to "Preparing your workspace..." with no button, and on winvm stayed that way for hours) | Keeps the last stop message until the next run starts; the card asks for it when it loads | port-7380-taken.sh reload |
| Windows Update restarts the PC in the middle of setup | Hydrogen comes back at sign-in and carries on | Starts at Windows sign-in (registered by the installer) and resumes from the step it was on; on winvm (2026-10-07, 03:23) it came back, found the workspace gone and rebuilt it in 72 seconds | Seen live on winvm |
| Adom's own servers are down while you set up | Setup stops at "The editor didn't finish starting" | Run setup again (or reopening Hydrogen) picks up where it stopped once Adom is back: on winvm the step that had failed during the 2026-10-07 outage passed in 10 seconds afterwards | Seen live on winvm |
For developers: running the scenarios
Each script lives in scripts/test-scenarios/ in the Hydrogen source and has three phases: arm (put the test PC into the bad state), check (exit 0 means Hydrogen handled it), and disarm (always run it, even after a failure). They run on the Azure test VM winvm with the tester's remote-desktop view open. The ralph skill lists them under "Regression scenarios (run on EVERY build)"; adding a pitfall to this page means adding a script there too.
# Setup steps pitfalls
Everything we know can go wrong while Hydrogen sets itself up on a Windows PC, what the person in front of the screen sees when it does, and what Hydrogen does about it. Each pitfall is a real report from a user or a test box, and the ones we can reproduce have a scenario script that runs against every build before it ships, so a fix stays fixed.
If you hit something during setup that is not on this page, please use **Report this problem** on the setup card. It's early days for Adom and unusual setups are exactly what we need to hear about; we try to fix reported problems within 2 hours.
## How setup works, in one paragraph
Hydrogen runs a Linux workspace (a WSL2 distro called `Adom-Workspace`) on your PC and puts a code editor and your AIs inside it. Setup does, in order: make sure WSL2 is on (installing it, with one Windows restart, if it is not), download and import the workspace image, connect the workspace to Windows (WSL's *mirrored networking*, so both share one `localhost`), start the editor, connect Adom Bridge (the link to your desktop apps), and finally check every piece for real before it calls itself done. Signing in to your AIs happens after setup, in the **Choose your AI** dialog.
## Recorded scenarios
Each video was recorded on a test PC with the build named in its caption, sped up where nothing is happening, with captions on every step.
| Scenario | What it shows | Video | Regression script |
|---|---|---|---|
| WSL2 installed from scratch | A PC that has never had WSL2: Hydrogen turns it on, asks for one restart, and finishes setup by itself afterwards | [video](wsl2-from-scratch.mp4) | `hd-vm-test.sh` (fresh snapshot) |
| Mirrored networking: first install and an advanced user's own choice | Hydrogen connects the workspace to Windows without asking; a user who deliberately set NAT keeps it, and the Your AIs dialog explains what that costs | [video](mirrored-networking.mp4) | `scripts/test-scenarios/wslconfig-mirrored.sh` |
| WSL's firewall blocks the workspace | A security tool or policy blocked WSL's network; Hydrogen allows exactly outbound and loopback with one admin prompt and finishes | [video](network-blocked.mp4) | `scripts/test-scenarios/wsl-network-blocked.sh` |
| Windows 10 | The installer stops right away with a clear message, before installing anything | [video](windows10.mp4) | installer gate (manual run on an Azure Windows 10 VM) |
| No hardware virtualization | A PC that cannot run WSL2: what it saw on 1.0.554 (installed WSL2, restarted, then hid the explanation behind other windows) and what 1.0.555 changes | [video](no-virtualization.mp4) | manual run on an Azure VM with the hypervisor off |
| Not enough disk space | With 0.8 GB free the import filled the drive, setup sat silent for ten minutes, then asked for a Windows restart; 1.0.556 checks for 8 GB first and stops in a second (verified on winvm); Adom Bridge's approval box covered that message, fixed for 1.0.557 | [video](disk-almost-full.mp4) | `scripts/test-scenarios/disk-almost-full.sh` |
| Expired Adom sign-in | The saved session is rejected; Hydrogen clears it and opens a fresh sign-in while setup carries on | [video](dead-session.mp4) | `scripts/test-scenarios/dead-session.sh` |
| Another WSL distro already running | Hydrogen never stops it on its own; when it needs one WSL restart it names the distro and lets you choose (1.0.559) | [video](other-distro-running.mp4) | `scripts/test-scenarios/other-distro-running.sh` |
| Workspace download blocked | Setup stops in seconds and says your network is blocking Adom's download server (1.0.557) | [video](image-download-blocked.mp4) | `scripts/test-scenarios/image-download-blocked.sh` |
| Another app holding the editor's port | A Windows app on 127.0.0.1:7380: from a generic error, to wrong advice, to naming the app in 20 seconds (1.0.560) | [video](port-7380-taken.mp4) | `scripts/test-scenarios/port-7380-taken.sh` |
| Damaged workspace image | Hydrogen notices the bad copy, fetches a fresh one and finishes (1.0.562) | [video](download-corrupt.mp4) | `scripts/test-scenarios/download-cache.sh corrupt` |
| Download cut short | Hydrogen resumes from where it stopped and finishes (1.0.562) | [video](download-resume.mp4) | `scripts/test-scenarios/download-cache.sh resume` |
| Sign-in window closed, or its link expired | Hydrogen brings the sign-in back, and after expiry opens a fresh link (1.0.565) | [video](signin-window.mp4) | `scripts/test-scenarios/signin-window.sh` |
| Workspace deleted after setup finished | Before 1.0.565 the editor waited forever; now Hydrogen notices at launch and rebuilds it | [video](workspace-gone.mp4) | `scripts/test-scenarios/state-recovery.sh gone` |
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/wsl2-from-scratch.mp4" style="max-width:100%;height:auto"></video>
*WSL2 from scratch, recorded on 1.0.554 on a clean Windows 11 PC with no WSL2. About 10 minutes of setup work: the installer, turning on WSL2 (about 30 seconds), one restart that waits for the user's click, then Hydrogen resumes by itself, builds the workspace and asks for the Adom sign-in. The frames where the tester typed their account details are replaced by a card.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/no-virtualization.mp4" style="max-width:100%;height:auto"></video>
*A PC that cannot run WSL2 (an Azure VM with the Windows hypervisor turned off), on 1.0.554. Captions say what 1.0.555 changes.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/disk-almost-full.mp4" style="max-width:100%;height:auto"></video>
*Not enough disk space (0.8 GB free on C:), on 1.0.554. Fixed in 1.0.556.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/windows10.mp4" style="max-width:100%;height:auto"></video>
*Windows 10 22H2: the installer stops before installing anything.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/mirrored-networking.mp4" style="max-width:100%;height:auto"></video>
*Mirrored networking, recorded on 1.0.552: first install turns it on with no question, the original setting is saved for uninstall, a user who sets NAT is respected, and the Your AIs dialog warns about AI sign-in. (On 1.0.554 and later the setup card no longer shows a warning at all; the Your AIs dialog is the only place it appears.)*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/network-blocked.mp4" style="max-width:100%;height:auto"></video>
*WSL's firewall blocks the workspace, recorded on 1.0.554: Hydrogen finds outbound and loopback blocked, allows exactly those two with one admin prompt (this test PC has UAC off, so the prompt does not show), and setup finishes on its own.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/dead-session.mp4" style="max-width:100%;height:auto"></video>
*Expired Adom sign-in, recorded on 1.0.559: Hydrogen clears the dead session and opens a fresh sign-in; setup carries on.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/other-distro-running.mp4" style="max-width:100%;height:auto"></video>
*Another WSL distro running, 1.0.556 then 1.0.560: Hydrogen never stops it on its own; it explains the one restart it needs, lets you choose, and the button finishes setup (pressed and verified on 1.0.560).*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/image-download-blocked.mp4" style="max-width:100%;height:auto"></video>
*Workspace download blocked, 1.0.556 then 1.0.559: from the wrong advice to a plain explanation.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/port-7380-taken.mp4" style="max-width:100%;height:auto"></video>
*Another app on the editor's port, 1.0.556, 1.0.559 and 1.0.560: Hydrogen now asks Windows who is listening and names the app.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/download-corrupt.mp4" style="max-width:100%;height:auto"></video>
*A damaged workspace image, recorded on 1.0.562: the fingerprint check catches it and setup quietly downloads a fresh copy.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/download-resume.mp4" style="max-width:100%;height:auto"></video>
*A download cut short, recorded on 1.0.562: setup resumes from 250 MB instead of starting over.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/signin-window.mp4" style="max-width:100%;height:auto"></video>
*The Adom sign-in closed and then expired, recorded on 1.0.565: Hydrogen brings it back, and after the link expires it opens a fresh one.*
<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/workspace-gone.mp4" style="max-width:100%;height:auto"></video>
*The workspace deleted after setup finished, 1.0.564 then 1.0.565: from stuck forever to a rebuild in about a minute and a half.*
## The pitfalls, by setup phase
**Tested by** names the scenario script that reproduces it on a test PC. *Not yet* means it is documented here and handled in the code, but has no automated reproduction yet.
### Before WSL2 is involved
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| ARM64 PC (Surface Pro X and similar) | Setup stops: "This PC's processor is ARM64; Hydrogen needs an x64 PC" | Stops before the 800 MB download; nothing else is changed | Not yet (adom/hydrogen#89) |
| Setup started twice at once | Nothing: setup runs once | A lock makes the second start a no-op: seen live on winvm (2026-10-07), two starts 0.6 seconds apart logged "already running, ignoring duplicate invocation" and setup completed normally | Seen live on winvm |
| Saved progress says done but the workspace is gone (an uninstall and reinstall, `wsl --unregister`, a cleanup tool) | 1.0.565: setup runs again by itself and the workspace is back in about 95 seconds (was, on 1.0.564: "Your workspace is ready" next to an editor stuck on "Starting AI Environment..." forever) | At launch it checks that the workspace really exists (an instant registry read) and rebuilds it if it does not | `state-recovery.sh gone`, [video](workspace-gone.mp4) |
| Workspace there but the editor died with an old Hydrogen | Editor stuck on "Starting" | Re-runs the workspace and editor steps | Not yet |
| A step left "running" by a crash | Nothing: setup carries on | Re-runs the step on the next launch and finishes (verified on 1.0.565: done in 67 seconds) | `state-recovery.sh stuck` |
| A minute of silence on a cold PC | (was) a dead panel | Reads Windows' registry instead of waking WSL, and narrates | Not yet |
| A console window flashes during install | A black terminal pops up | Every helper runs hidden | Not yet |
| An old Adom Bridge from a previous install still running | Setup talks to a leftover | Reclaims stale processes; the uninstaller cleans up | Not yet |
### Turning on WSL2 (and the one restart)
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| WSL2 is not installed | The card explains, one Windows permission prompt, then Restart now / Restart later | Installs WSL2 itself, shows the download and Windows' own progress, never restarts without your click, and resumes setup after the restart | `hd-vm-test.sh` |
| You click No on the permission prompt (or miss it over remote desktop) | "One quick permission to turn on WSL2" with a button to ask again | Waits for you; the button asks again | Not yet |
| GitHub is blocked on your network | "Couldn't download WSL2: this PC can't reach github.com" | Names the network problem instead of blaming your Windows edition | Not yet |
| WSL2 still missing after the install and restart | Manual steps for an admin PowerShell | Stops instead of restarting in a loop | Not yet |
| No hardware virtualization (BIOS setting off, an older or locked-down laptop, or a virtual machine without nested virtualization) | "This PC can't run Hydrogen's workspace yet", two sentences, and a How to turn on virtualization button that opens Microsoft's how-to in front (verified on 1.0.560, including a 1024x768 screen) | Checks before installing WSL2 when Windows can tell (no hypervisor running and virtualization off in firmware); otherwise stops at the first workspace build with the same message, and brings the card to the front | [video](no-virtualization.mp4) |
| Windows 10, or Windows 11 before 22H2 | The installer says "Adom Hydrogen needs Windows 11, version 22H2 or newer" with the PC's version and build | Stops before installing anything. Before 1.0.555 the gate let Windows 11 21H2 through (build 22000), which then failed in setup, and named the wrong reason | [video](windows10.mp4) |
| Restart later | Setup waits; a gentle reminder every few minutes | Never forces a restart; finishes after whatever restart you choose | Not yet |
| Edge says "Restore pages: Microsoft Edge closed unexpectedly" after the restart | A bubble over the Adom sign-in page | Nothing yet: the restart closed Edge, and Edge offers to restore it. Harmless, but confusing at the one moment we need the user | `hd-vm-test.sh` (seen 2026-10-06) |
| Windows asks "Allow important notifications from Adom Bridge?" | A Windows prompt about an app the user has never heard of, on top of the sign-in (Seen on test PCs signed in to an account whose Adom Bridge is linked to other machines, which mirror their alerts in; still to confirm on a single-PC account.) | Nothing yet: Adom Bridge asks for that permission on its first start, which lands during setup. To fix: ask later, after setup | `hd-vm-test.sh` (seen 2026-10-06) |
| Edge's own first-run welcome takes over the screen | A brand-new PC: the first thing that opens Edge (the Adom sign-in) gets "Welcome to Microsoft Edge" first | Nothing yet; the user clicks through Edge's welcome. Seen on a fresh Windows 11 VM, 2026-10-06 | Not yet |
| Hydrogen's message hidden behind other windows when setup stops | (was) the Adom sign-in in Edge and Adom Bridge's red activity log on top, Hydrogen's explanation found last (Seen on test PCs signed in to an account whose Adom Bridge is linked to other machines, which mirror their alerts in; still to confirm on a single-PC account.) | 1.0.555 brings the setup card to the front when setup stops (only then) | [video](no-virtualization.mp4) |
| Windows Defender flags an unsigned helper as a trojan | The program disappears | Hydrogen and Adom Bridge are code-signed; on a Windows 10 test PC Defender's machine-learning check quarantined our own unsigned test robot (`Trojan:Win32/Bearfoos.B!ml`), not anything we ship | Seen on a test PC, 2026-10-06 |
| Windows' "You're almost done setting up your PC" page after the restart | (was) that page covered Hydrogen | Turns those pages off before the restart | Not yet |
| The "Welcome to WSL" window pops over Hydrogen | A stray WSL window | Minimizes it | `hd-vm-test.sh` |
| WSL is wedged before the install | A heartbeat, then a gentle restart countdown | Clears stuck WSL processes, asks for a restart at most twice, then gives manual steps | Not yet |
### Building the workspace
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| Slow download of the workspace image | Progress with size, speed and time left | Starts the download early (it overlaps the WSL restart) and resumes after an interruption | Not yet |
| Download cut short (restart, crash, network drop) | Nothing alarming: setup keeps building | Resumes from where it stopped and checks the finished file (verified on 1.0.562: resumed from 250 MB) | `download-cache.sh resume`, [video](download-resume.mp4) |
| Corrupt download, or a damaged cached image | Nothing alarming: setup keeps building | The SHA-256 check catches it, deletes the copy and downloads a fresh one without stopping (verified on 1.0.562) | `download-cache.sh corrupt`, [video](download-corrupt.mp4) |
| The workspace download is blocked (company network, VPN, proxy, security tool) | 1.0.557+: "Hydrogen couldn't download your workspace. Your PC could not reach Adom's download server..." (was, on 1.0.556: "open PowerShell and run wsl --unregister", the wrong fix) | Stops within seconds, no hang, no crash; Run setup again resumes once the network allows it | `image-download-blocked.sh`, [video](image-download-blocked.mp4) |
| Not enough disk space | 1.0.556: "Your C: drive is almost full (N GB free). Hydrogen's workspace needs about 8 GB..." before anything is built | Checks before building; if a drive fills anyway, the four-minute no-progress watchdog says the drive is full instead of asking for a Windows restart (which it did before) | `disk-almost-full.sh`, [video](disk-almost-full.mp4) |
| A workspace left half-registered by a crash | (was) every import failed | Removes only Hydrogen's own leftover and imports again | Not yet |
| Another WSL command during the workspace's first boot | (was) a permanently broken workspace | One WSL command at a time while it boots | Not yet |
| The workspace never finishes booting | "WSL2 looks wedged: run wsl --shutdown, then Run setup again" | Stops with the exact fix | Not yet |
| WSL's management service throws "Catastrophic failure" | Retries, then the fix | Retries with backoff, never shuts down your other WSL distros | `HD_TEST_WSL_FAIL` test hook |
| Other WSL distros running (Docker Desktop, your own Ubuntu) while a setting needs a WSL restart | 1.0.559: "Hydrogen needs to restart WSL once. Another Linux distribution is running (*name*)... Restarting WSL stops *name* too: save your work there, then restart." with a Restart WSL and finish setup button (was: "This usually clears up on its own: run setup again", which never could, verified on 1.0.556) | Never stops your distros on its own; the restart happens only when you press the button, then setup finishes (verified on 1.0.560) | `other-distro-running.sh` (adom/hydrogen#85), [video](other-distro-running.mp4) |
| A busy workspace mistaken for a broken disk | (was) a WSL restart, then a request to restart Windows on a healthy PC | Waits for a real answer; only a real disk failure counts | Not yet (found on a test PC, 2026-10-06) |
| A busy workspace mistaken for a missing editor | (was) the editor reinstalled from scratch | Only reinstalls on a real "not installed" | Not yet (found on a test PC, 2026-10-06) |
### Connecting the workspace to Windows (networking)
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| WSL's default networking (NAT) | "Connecting your workspace to Windows" | Turns on mirrored networking, saves your original setting, and puts it back if you uninstall | `wslconfig-mirrored.sh` |
| You deliberately set another networking mode | Nothing during setup; the Your AIs dialog warns that AI sign-in needs mirrored networking, with a button to turn it back on | Respects your choice and never changes it back on its own | `wslconfig-mirrored.sh` (adom/hydrogen#100) |
| A security tool or policy set WSL's firewall to block it | (was) setup stopped at "Building your workspace" | One WSL restart, then one admin prompt that allows exactly outbound traffic and loopback; inbound stays blocked | `wsl-network-blocked.sh` (adom/hydrogen#100), [video](network-blocked.mp4) |
| The network comes back slowly after that fix | (was) "not confirmed", and Try again worked a minute later | Waits up to 90 seconds for the network, then carries on | `wsl-network-blocked.sh` |
| Your organization's policy overrides the firewall | "A policy managed by your organization may be overriding it" | Says so and carries on | Not yet |
| Windows too old for mirrored networking (before Windows 11 22H2) | The installer stops (see Windows 10 above) | Since 1.0.555 the installer's own minimum is 22H2, so setup never meets this | [video](windows10.mp4) |
| A full-tunnel VPN | Windows is online but the workspace is not | Names the VPN adapter after setup | Not yet (adom/hydrogen#77) |
| A Windows proxy leaking into WSL | (was) a false "port taken" error | Checks from Windows first, bypassing the proxy | Not yet (adom/hydrogen#89) |
### Starting the editor
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| Windows can't reach the editor | "Windows could not reach the workspace: a VPN, security tool or firewall" | Three repair rounds, then the network fix, then a clear diagnosis | `wsl-network-blocked.sh` |
| Port 7380 already taken by a Windows app | 1.0.560: "Another app is using Hydrogen's editor port. Port 7380 is in use by *app name* on Windows, and Hydrogen's editor needs it. Close *app name*, then run setup again." within about 20 seconds (was: the generic "Setup didn't finish" on 1.0.556; on 1.0.559 the stranger fooled an early check, the editor pane loaded it, and the card said "run wsl --unregister") | Asks Windows which app is listening before trusting the port, at every step that checks it, and stops without retrying | `port-7380-taken.sh`, [video](port-7380-taken.mp4) |
| The editor listening on your whole network | (was) a passwordless editor visible on your Wi-Fi | Listens on this PC only, and moves older installs over at launch | ralph `codeserver.localhost_only` (adom/hydrogen#100) |
| The editor waits for your Adom sign-in | "Waiting for you to finish signing in to Adom" | Waits as long as you need | `hd-vm-test.sh` |
| The editor's extension never starts | "The editor didn't finish starting" | Run setup again restarts it | Not yet |
### Signing in
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| You close the Adom sign-in window | The sign-in comes back within seconds, and the card offers "Open the sign-in" | Reopens it by itself, then shows a button (verified on 1.0.565) | `signin-window.sh`, [video](signin-window.mp4) |
| The sign-in link expires (about 15 minutes) | "Open the sign-in" opens a fresh link | Never reopens a dead link: after 16 minutes the button opened a brand new one (verified on 1.0.565) | `signin-window.sh`, [video](signin-window.mp4) (adom/hydrogen#39) |
| You sign in hours later | Setup waits | No deadline; carries on when you sign in | Not yet |
| A saved sign-in from an old install has expired | The Adom sign-in page opens with one Approve button (verified on 1.0.559; was: stuck 6 minutes at "Opening your editor") | Checks the saved sign-in with Adom at launch; if it is dead, clears it and asks you to sign in fresh while the workspace keeps building | `dead-session.sh`, [video](dead-session.mp4) |
| The sign-in opens in Edge instead of your browser | (was) the wrong browser | Opens your default browser | Not yet |
### Adom Bridge (your desktop apps)
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| Adom Bridge can't be installed (no network) | A note that Hydrogen will retry on its next launch | Carries on; it is not needed to finish setup | Not yet |
| Adom Bridge slow to start | A note; it keeps trying | Carries on | Not yet |
| The connection to your desktop apps doesn't start | "Adom Bridge isn't connected yet: run setup again" | Run setup again restarts it | Not yet |
| Adom Bridge's approval box covers Hydrogen when setup stops early | (was) "Permission requests: The cloud AI wants to run shell / system commands on this machine" on top of Hydrogen's explanation, for a request nobody was waiting on | 1.0.557 asks Adom Bridge for that approval only after the workspace is built, so a stop during the build never raises it ([adom-bridge#228](https://wiki.adom.inc/adom/adom-bridge/issues/228) for withdrawing a pending box) | `disk-almost-full.sh`, [video](disk-almost-full.mp4) |
### The final check and the setup card
| Pitfall | What you see | What Hydrogen does | Tested by |
|---|---|---|---|
| A check fails at the very end | A title that names the problem, one sentence on what to do, and one button that says what it does (for example Run setup again, or Reconnect and finish setup) | Every failure has a plain explanation; Continue anyway skips ahead; Report this problem sends us the log | Any scenario that stops |
| (was) the card quoted a log line and offered Try again / Open Hydrogen / Report side by side | | Replaced on 1.0.554 | |
| The setup card reloads after setup stopped (WebView2 can do this on its own) | 1.0.564: the stop message and its buttons are still there (was: the card went back to "Preparing your workspace..." with no button, and on winvm stayed that way for hours) | Keeps the last stop message until the next run starts; the card asks for it when it loads | `port-7380-taken.sh reload` |
| Windows Update restarts the PC in the middle of setup | Hydrogen comes back at sign-in and carries on | Starts at Windows sign-in (registered by the installer) and resumes from the step it was on; on winvm (2026-10-07, 03:23) it came back, found the workspace gone and rebuilt it in 72 seconds | Seen live on winvm |
| Adom's own servers are down while you set up | Setup stops at "The editor didn't finish starting" | Run setup again (or reopening Hydrogen) picks up where it stopped once Adom is back: on winvm the step that had failed during the 2026-10-07 outage passed in 10 seconds afterwards | Seen live on winvm |
## For developers: running the scenarios
Each script lives in `scripts/test-scenarios/` in the Hydrogen source and has three phases: `arm` (put the test PC into the bad state), `check` (exit 0 means Hydrogen handled it), and `disarm` (always run it, even after a failure). They run on the Azure test VM `winvm` with the tester's remote-desktop view open. The ralph skill lists them under "Regression scenarios (run on EVERY build)"; adding a pitfall to this page means adding a script there too.