Document --remote-allow-origins=* requirement for Chromium 128+ origin allowlist

[nikolay-bratanov]

The README's "Enable remote debugging in Chrome" section says:

Navigate to chrome://inspect/#remote-debugging and toggle the switch. That's it.

On modern Chromium (128+) this isn't sufficient. The toggle enables the debug port (writes DevToolsActivePort to the profile), but the WebSocket endpoint enforces an Origin allowlist that's empty by default. External clients are rejected, and cdp list fails with the cryptic WebSocket error: error.

Symptoms

cdp.mjs connects via Node's built-in WebSocket, which sends no Origin header. Chromium's behavior:

• WebSocket upgrade with no Origin → connection silently closed (no HTTP response)

• WebSocket upgrade with non-allowlisted Origin → HTTP 403 with a helpful body:

  Rejected an incoming WebSocket connection from the <origin> origin. Use the command line flag --remote-allow-origins=<origin> to allow connections from this origin or --remote-allow-origins=* to allow all origins.

cdp list surfaces only the silent-close case as WebSocket error: error, which doesn't hint at the launch flag.

Reproduction (Helium 0.11.7.1, Chromium 147 base, macOS 15)

1. Open chrome://inspect/#remote-debugging, toggle the switch on.
2. Verify ~/Library/Application Support/net.imput.helium/DevToolsActivePort exists and 127.0.0.1:9222 accepts TCP.
3. cdp list → WebSocket error: error, exit 1.
4. Quit, relaunch with --remote-allow-origins=*:

   open -a Helium --args --remote-allow-origins='*'

5. cdp list → tabs listed, all commands work.

I haven't tested whether stock Google Chrome bypasses this somehow (DevTools UI may register an internal allowlist entry), but on the Chromium upstream code path the requirement is universal post-128.

Suggested fix

Add a brief note in the "Enable remote debugging" section, e.g.:

Enable remote debugging in Chrome

Navigate to chrome://inspect/#remote-debugging and toggle the switch.

Chromium 128+: also launch the browser with --remote-allow-origins=*
(or a specific allowed Origin) — the toggle enables the port but does not
allowlist any external client. Without this flag, cdp list will fail with
a generic WebSocket error: error because Chromium silently drops
WebSocket upgrade requests that have no Origin header.

Optionally, cdp.mjs could detect the silent-close case and surface a more actionable error message ("Chromium dropped the WebSocket — did you launch with --remote-allow-origins?"), but that's cosmetic — the doc note alone would have saved hours on my end.

Related

• A small follow-up PR adding Helium (net.imput.helium) to the macOS browser candidates is in flight.
• Background on the allowlist: Chromium DevTools "Resolved Issue 1009350" and the --remote-allow-origins switch landed in Chromium 111.