Windows Host Browser

Windows host browser

The target is a long-lived Chrome on Iliyas's Windows PC, started with --remote-debugging-port=<PORT> --user-data-dir="C:\chrome-debug". It is not a headless sandbox: it is a real browser Iliyas also uses, with his live sessions (Vercel, Google Cloud, and more), rendered on his physical screen.

Two consequences drive everything below:

• Power — anything behind his logins is reachable without asking for credentials, and a page can be debugged exactly as he sees it: open tabs, run JS in them, watch network traffic, route through a chosen proxy.
• Restraint — he sees every window you open and shares every setting you change. Use this browser only on his explicit request; when he names the browser in the request, that settles it. Tell him when you open something visible, close tabs you opened unless he wants them kept, and undo browser-wide changes (proxy!) when done. For data you could equally get by asking him or via an authed CLI, prefer that.

Step 0 — connect: run connect.sh, use the fixed endpoint

On dev-remote the endpoint is fixed: http://127.0.0.1:18800, no matter which port Chrome uses on the Windows side. One command sets everything up:

~/.agents/skills/windows-host-browser/connect.sh
# on success prints:  CDP_HTTP=http://127.0.0.1:18800
export CDP_HTTP="http://127.0.0.1:18800"

The script is idempotent and cheap when everything is already up. When it isn't, it rediscovers the current Windows-side port from the chromedebug scheduled task (the source of truth — the port moves, see "Port gotcha"; never hardcode it), relaunches Chrome via the task if the process is dead (a visible window on Iliyas's screen — say so), and rebuilds both SSH hops (dev-remote → wsl → windows) onto local port 18800.

A systemd timer on dev-remote re-runs it every 2 minutes, so the endpoint is normally already alive: systemctl status cdp-tunnel.timer, logs in journalctl -u cdp-tunnel.service.

If connect.sh prints FAIL, its message names the layer that broke; the sections below are the manual troubleshooting path. As of 2026-09-01 the Windows-side port is 9555 (9222, 9223, 9250, 9333 and 9444 got WinNAT-blocked in turn).

Manual path (what connect.sh automates)

The debug port lives only on the Windows host's own loopback. The home machine (the WSL box iliyasone) and dev-remote are both on Iliyas's Tailscale tailnet, the stable path between them. Reaching the port is a two-hop tunnel — the WSL box cannot see the Windows loopback directly, so it must tunnel to the host too. Discover the port first:

PORT=$(ssh wsl 'ssh windows "schtasks /query /tn chromedebug /xml"' \
        | grep -aoE 'remote-debugging-port=[0-9]+' | grep -oE '[0-9]+')

• On the WSL box iliyasone: bring the host port onto WSL's loopback:

  pgrep -f "ssh .*-L $PORT:127.0.0.1:$PORT windows" >/dev/null \
    || ssh -f -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 \
           -L "$PORT:127.0.0.1:$PORT" windows
  

  (ssh windows "curl 127.0.0.1:$PORT/json/version" also works without the tunnel, for one-off checks.)

• On dev-remote: ssh wsl reaches the WSL shell over the tailnet (100.93.231.101). Chain a second forward on top of the WSL→host one above:

  pgrep -f "ssh -N .*-L $PORT:127.0.0.1:$PORT wsl" >/dev/null \
    || setsid ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 \
             -L "$PORT:127.0.0.1:$PORT" wsl >/dev/null 2>&1 < /dev/null &
  

Then run the check:

curl -s --max-time 4 "http://127.0.0.1:$PORT/json/version" || echo NO_CDP

A Chrome version → go to Step 1. NO_CDP → causes, cheapest first: a tunnel isn't up (re-run the forwards above); the port was stolen by WinNAT even though Chrome is running (see "Port gotcha"); the home PC / WSL box is offline (tailscale status — if iliyasone is offline, the machine is off, nothing to fix from here); or the debug Chrome isn't running (see "Launching"). Do not fabricate a path.

Step 1 — connect

One gotcha applies to every websocket connection, not just the helper: Chrome was started without --remote-allow-origins, so open CDP websockets with no Origin header or the connection is rejected.

From there it is plain CDP against $CDP_HTTP:

• GET /json/list — tabs and their websocket URLs; attach with any CDP client to evaluate JS, capture screenshots, or watch network events (Network.enable + Network.requestWillBeSent / responseReceived).
• PUT /json/new?url=… — open a page (a visible tab on Iliyas's screen — say so when you do it).

Reuse existing windows — don't multiply them

Every window and tab is on Iliyas's screen, and he has asked agents to stop spawning new windows. Before opening anything, GET /json/list and reuse what's there, in this order:

1. A blank tab exists (about:blank or chrome://newtab/): navigate it (attach to its websocket, Page.navigate) instead of creating a target.
2. The open tabs are your own or clearly idle (not something Iliyas is actively working in): open your page as a tab in that same window — PUT /json/new does this, it targets an existing window.
3. A new window only when you deliberately want one — e.g. the existing window is full of Iliyas's unrelated active work, or you need isolation (different window size, a flow he should watch separately). Say why.

Same on cleanup: /json/close/<id> the tabs you opened; never close tabs you didn't open.

Proxy control — cdp.py (per profile)

Chrome carries the Proxy Switcher extension (iejkjpdckomcjdhmkemlfdapjodcpgih), which owns the proxy setting. The proxy is per Chrome profile, not per window: the browser can run several profiles at once (separate windows, cookies, extension copies), and each can sit behind a different proxy. cdp.py (next to this file) drives it. It defaults to the fixed endpoint http://127.0.0.1:18800 (run connect.sh first); $CDP_HTTP overrides that only when running somewhere else.

python3 cdp.py profiles             # list running profiles by their open tabs
python3 cdp.py get -p 2             # proxy setting of profile 2 from that list
python3 cdp.py set 82.38.65.142 41196 http proxyuser 'PASSWORD' -p proton
python3 cdp.py egress -p proton     # prove the exit IP/country through it
python3 cdp.py direct -p proton     # revert that profile to direct

--profile / -p takes an index from profiles or a substring of a URL/title of a tab open in that profile. With a single profile running it can be omitted; with several it is required — the tool refuses to guess, because setting a proxy on the wrong profile changes what Iliyas is browsing through.

Two gotchas the tool hides: the extension is MV3, so its per-profile service worker sleeps and drops out of the target list — and a sleeping worker in a specific profile can't be woken via Target.createTarget (CDP refuses real profiles' browserContextIds). cdp.py wakes it by window.opening a throwaway tab from one of that profile's own pages, CDP-navigating it to the extension popup, then closing it.

set calls chrome.proxy.settings.set for that profile (exactly what the extension popup does) and, when a username is given, writes the extension's auth-username/auth-password storage and re-arms its onAuthRequired handler so authenticated proxies don't pop a dialog.

Always direct when done on the profile Iliyas browses in himself — a proxy left there changes his own browsing. A dedicated proxy profile can keep its proxy.

Adding the extension to a new profile is a manual step: open https://chromewebstore.google.com/detail/iejkjpdckomcjdhmkemlfdapjodcpgih in that profile's window and have Iliyas click "Add to Chrome" — the install confirmation is native UI, unreachable over CDP.

Where proxies come from

The reverse-api project owns a proxy table (Postgres, Heroku app pinc000): columns scheme, server, port, username, password, country_code. HTTP proxies with user/pass auth, selected by country_code (ISO-3166 alpha-2). Query it rather than hardcoding credentials:

# on dev-remote, heroku CLI is authed to app pinc000
heroku pg:psql -a pinc000 -c \
  "select scheme,server,port,username,password,country_code from proxy where country_code='nl';"

There is no rotation — a proxy is sticky per account — so for browser use pick any row for the country you want.

Launching the debug Chrome

If Step 0 says NO_CDP but ssh wsl works, start Chrome via the scheduled task — never over plain SSH, which lands Chrome in the invisible session 0 where it exits without ever binding the port:

# from the WSL box:
ssh windows 'schtasks /run /tn chromedebug'
# from dev-remote (hop through WSL):
ssh wsl 'ssh windows "schtasks /run /tn chromedebug"'
# then poll: curl -s "$CDP_HTTP/json/version"

This opens a visible window on Iliyas's screen — say so when you do it. The task runs as LogonType=InteractiveToken (General tab: "Run only when user is logged on"), so it launches into his visible session and stores no password.

If the relaunch works but Chrome is dead again minutes later, don't keep relaunching — see "Death gotcha".

Iliyas can open it himself — the desktop shortcut

"Agent Chrome" on the Windows desktop opens this browser by hand — e.g. to sign in to a service so agents can then use the session. It runs C:\chrome-debug\open-debug-chrome.ps1: if the debug Chrome is already running it opens a new window in it; otherwise it starts the chromedebug task (a plain schtasks /run would be silently ignored while the task instance is still running, because the task uses MultipleInstances IgnoreNew — that's why the script checks first). So when he needs to log in somewhere, point him at the shortcut instead of opening tabs for him.

If the shortcut or opener script is missing, recreate both by running mk-shortcut.ps1 (next to this file) on the host via the -EncodedCommand transport. It builds the .lnk in C:\chrome-debug and moves it to the desktop — WScript.Shell fails to save directly into the desktop folder because its name is Cyrillic (Рабочий стол).

Port gotcha — WinNAT can steal the debug port

Symptom: the debug Chrome is running and browses fine, but $CDP_HTTP/json/version refuses the connection and no DevTools server exists. Launched with --enable-logging --v=1, C:\chrome-debug\chrome_debug.log shows bind() ... Only one usage of each socket address ... (0x2740) then Cannot start http server for devtools.

Cause: Hyper-V/WSL2 WinNAT/HNS reserves blocks of TCP ports; after a WSL or host restart a block can include the debug port. It becomes unbindable even though netstat shows nothing on it AND it is absent from netsh int ipv4 show excludedportrange. "Worked yesterday, broken today" = the reserved block moved onto the port. Custom user-data-dir, policies, and session 0 are red herrings here — confirm with the log line above.

Recovery (no admin, no service restart):

1. Find a free port — try to bind candidates and pick the first that succeeds:

   foreach ($p in 9223,9250,9333,9555,18222) {
     try { $l=[System.Net.Sockets.TcpListener]::new([Net.IPAddress]::Loopback,$p)
           $l.Start(); "OK $p"; $l.Stop() } catch { "FAIL $p" } }
   

2. Repoint the task to that port. Use PowerShell Set-ScheduledTask, not schtasks /change — the latter wrongly prompts for a Windows password even though the task stores none:

   $a = New-ScheduledTaskAction -Execute 'C:\Program Files\Google\Chrome\Application\chrome.exe' `
        -Argument '--remote-debugging-port=<PORT> --user-data-dir=C:\chrome-debug'
   Set-ScheduledTask -TaskName 'chromedebug' -Action $a
   

   Quoting through ssh wsl 'ssh windows "..."' is brittle; run PowerShell via -EncodedCommand <base64-UTF16LE> to avoid it.

3. Kill the old instances, relaunch, verify:

   Get-CimInstance Win32_Process -Filter "name='chrome.exe'" |
     ? { $_.CommandLine -like '*chrome-debug*' } | % { Stop-Process $_.ProcessId -Force }
   schtasks /run /tn chromedebug
   (Invoke-WebRequest -UseBasicParsing http://127.0.0.1:<PORT>/json/version).Content
   

4. Re-run the Step 0 tunnels with the new $PORT.

Durable fix (optional, needs admin): reserve the port so WinNAT won't grab it — net stop winnat; netsh int ipv4 add excludedportrange protocol=tcp startport=<PORT> numberofports=1 store=persistent; net start winnat. Stopping winnat briefly drops WSL2/Hyper-V NAT, which can blip an SSH path that runs through it — do it only when a short interruption is safe.

Death gotcha — Task Scheduler kills Chrome on battery flap

Symptom: the opposite of the Port gotcha — the debug Chrome process dies minutes after every launch (0 chrome.exe with chrome-debug in the command line), while the debug port is free and bindable. schtasks /run /tn chromedebug brings CDP back, then it's dead again within ~2 minutes.

Cause: the PC is a laptop, and a task created with default settings gets StopIfGoingOnBatteries=true / DisallowStartIfOnBatteries=true. Windows' AC/battery status can flap every couple of minutes even with the charger plugged in (battery-care charge limiting, loose connector), and on every flap Task Scheduler terminates the task's Chrome. The proof is Task Scheduler operational-log event 327: Task Scheduler stopped instance ... of task "\chromedebug" because the computer is switching to battery power. The chromedebug task already carries the fixed settings, but any recreation of the task with New-ScheduledTask/Register-ScheduledTask default settings silently reintroduces the killers — so re-check the settings whenever this symptom returns.

Diagnose:

1. schtasks /query /tn chromedebug /xml — in <Settings>, StopIfGoingOnBatteries / DisallowStartIfOnBatteries must be false and ExecutionTimeLimit PT0S (unlimited). If they aren't, that's the bug — go straight to the fix.

2. The Task Scheduler operational log is disabled by default; enable it and catch the next death in the act:

   wevtutil sl Microsoft-Windows-TaskScheduler/Operational /e:true
   # after a death:
   Get-WinEvent -LogName 'Microsoft-Windows-TaskScheduler/Operational' -MaxEvents 100 |
     ? { $_.Message -match 'chromedebug' } | select TimeCreated, Id, Message
   

   Event 327 with "switching to battery power" = this gotcha. No 32x stop-event at all = Chrome itself crashed — add --enable-logging --v=1 to the task action, reproduce, read C:\chrome-debug\chrome_debug.log, then revert the flags.

3. Battery reality check: Get-CimInstance Win32_Battery (a result means it's a laptop) and [System.Windows.Forms.SystemInformation]::PowerStatus (after Add-Type -AssemblyName System.Windows.Forms) for the current AC state.

Durable fix — replace the task's settings, keeping the action and the InteractiveToken principal (Set-ScheduledTask never touches parts you don't pass). Put this in a .ps1 and run it through the -EncodedCommand transport rather than quoting it inline across the two SSH hops:

$s = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
     -ExecutionTimeLimit ([TimeSpan]::Zero) -MultipleInstances IgnoreNew
Set-ScheduledTask -TaskName 'chromedebug' -Settings $s

# from dev-remote: encode UTF-16LE+base64, run via the double hop
B64=$(iconv -f UTF-8 -t UTF-16LE /tmp/fix.ps1 | base64 -w0)
ssh wsl "ssh windows 'powershell -NoProfile -EncodedCommand $B64'"

(-ExecutionTimeLimit zero matters: New-ScheduledTaskSettingsSet otherwise defaults it to 72 h, which would kill Chrome three days in.) Then relaunch and — the real test — confirm the process count is still non-zero 4–5 minutes later, past the flap interval, not just that CDP answered once.

How the access is wired (and repairing it)

Both machines are nodes on Iliyas's Tailscale tailnet:

• iliyasone = 100.93.231.101 — the WSL box on the home PC. Tailscale runs inside WSL, not on Windows; the Windows host is reached through WSL via ssh windows (→ 127.0.0.1:2222, key ~/.ssh/id_win). The Windows loopback is not shared into WSL, so reaching the debug port from WSL needs the ssh -L ... windows tunnel from Step 0.
• dev-remote = 100.105.176.17. Its ~/.ssh/config has Host wsl → 100.93.231.101, and its root key is in the WSL box's authorized_keys, so ssh wsl works over the tailnet.

Tailnet addresses survive home-IP changes, so nothing needs reconfiguring when Iliyas's network moves. When connect.sh fails (or a manual check says NO_CDP):

• Far end offline (PC asleep / WSL not up): tailscale status shows iliyasone offline. Nothing to fix from dev-remote.
• Chrome not running but ssh wsl works: see "Launching".
• Port stolen by WinNAT: see "Port gotcha".
• Chrome dies again right after relaunch: see "Death gotcha".
• Tunnel not up: re-run connect.sh (it rebuilds both hops).
• MTU blackhole on the tailnet path (seen 2026-08-15): ping works but ssh wsl hangs at expecting SSH2_MSG_KEX_ECDH_REPLY, or small CDP calls (/json/version) work while big ones (/json/list) return nothing — large packets are being dropped between dev-remote and iliyasone. Two-part fix: force a small classic KEX on every ssh to wsl (-o KexAlgorithms=curve25519-sha256@libssh.org,curve25519-sha256 — the default post-quantum sntrup761 KEX sends oversized packets), and lower the interface MTU on dev-remote: ip link set dev tailscale0 mtu 1200 (default 1280 exceeds the real path MTU). The MTU setting does not survive a dev-remote reboot, but connect.sh re-applies it on every non-fast-path run; check ip link show tailscale0 if big transfers stall anyway. Tunnels opened before the MTU fix keep their broken MSS — restart them after changing the MTU.

Only one home node is on the tailnet today (iliyasone). If Iliyas later works from a different machine, it joins as a separate node with its own name/IP — repoint Host wsl (or add Host wsl-<name>) at it. Do not invent non-tailnet routes.