chrome-mirror

Mirror a Chrome browser to a web viewer via the Chrome DevTools Protocol — multi-tab, zoom, remote host, keyboard + mouse passthrough.

Works against:

• a local Chrome started with --remote-debugging-port
• a remote Chrome (CDP over HTTP / WS)
• a browserless / chromiumoxide-style container (direct WS)

No Puppeteer, no Playwright — just a thin CDP relay + a canvas viewer.

Quick start

# Launch a local Chrome and mirror it (opens the viewer in your browser)
npx chrome-mirror mirror

# Connect to an existing Chrome on host:port
npx chrome-mirror connect --cdp-host 192.168.1.10 --cdp-port 9222

# Connect to a browserless / WS endpoint
npx chrome-mirror connect --cdp-url ws://localhost:3003

# With an auth token
npx chrome-mirror connect --cdp-url wss://chrome.example.com --cdp-token YOUR_TOKEN

Viewer opens at http://localhost:3000 (auto-bumps if busy, or set PORT=3300).

Commands

| Command | Description | |---|---| | mirror | Launch Chrome with stealth flags and start mirroring (default) | | connect | Attach to an already-running Chrome / browserless | | launch | Launch Chrome only (no mirror) |

Common flags

-p, --port <port>          Viewer HTTP port (default 3000, env PORT)
    --cdp-host <host>      CDP host (e.g. 192.168.1.10 or host:port)
    --cdp-port <port>      CDP port (default 9222)
    --cdp-url  <url>       Full CDP WebSocket URL (ws:// or wss://)
    --cdp-token <token>    Token appended as ?token= on the WS URL
    --no-open              Don't auto-open the viewer
-v, --verbose              Debug logging

Features

• Multi-tab strip — list, switch, close, and open new tabs in the remote browser
• Live CDP reconnect — exponential backoff on disconnect, with status dot in the UI
• On-the-fly host change — gear icon to reconfigure CDP target without restart
• Zoom via Emulation.setPageScaleFactor (works on chrome:// pages too)
• Binary input protocol for low-latency mouse / keyboard
• WebCodecs JPEG decode + OffscreenCanvas worker render for smooth frames
• /metrics Prometheus endpoint
• No detection — does not load Network domain, no CDP fingerprints injected

Viewer

• Address bar, back / forward / refresh
• Tab strip with favicons
• View-only mode, copy page text, copy selection, fullscreen
• Sidebar text panel (extracted DOM text)
• Settings modal for CDP host + token

Requirements

• Node.js ≥ 18
• A Chrome / Chromium with remote debugging enabled, or any CDP-compatible endpoint

Development

git clone https://github.com/nhdms/chrome-mirror
cd chrome-mirror
npm install
npm run dev        # tsx watch
npm run build      # esbuild bundle to dist/
npm test           # vitest

License

MIT