Remote Browser runs a web page on your server and rebuilds it as a scriptless, interactive page in your browser.

Text stays sharp, selectable, copyable, and locally findable. Visited-page JavaScript, cookies, and network sessions stay inside the remote Chromium. When a page cannot be faithfully rebuilt, media lanes and a whole-tab pixel mode cover the difficult parts.

Quick start · How it works · Configuration · Deployment · Security

Important

This is an early build for a small set of trusted viewers. Its scriptless DOM mirror is a different security boundary from pixel-only remote browsing. Read the security model before exposing it beyond localhost.

Quick start

You need Docker Engine and Docker Compose v2 on a modern Linux host.

git clone https://github.com/somewhereafter/remote-browser.git
cd remote-browser
./scripts/bootstrap.sh

The bootstrap creates local credentials, builds the two containers, waits for Chromium, and prints the URL and generated password. It leaves an existing .env untouched.

Open http://localhost:8080 and browse. The default deployment listens only on loopback and keeps the Chromium profile ephemeral.

docker compose ps
curl --fail http://localhost:8080/healthz

Stop it with:

docker compose down

How it works

The page remains authoritative in remote Chromium. An in-page recorder sends a snapshot and ordered changes to the gateway, which rebuilds them inside a sandboxed viewer without running the visited page's scripts. Input travels back to the real page through Chrome DevTools Protocol events.

This is not VNC. Ordinary pages remain semantic, so text and interaction can stay local and crisp. Canvas, video, WebGL, and divergent pages can fall back to scoped WebRTC or pixels.

The current build includes:

• tabs, navigation, pointer, keyboard, touch, IME, uploads, and downloads;
• ordered recovery and resync when a viewer falls behind;
• shadow DOM, cross-origin frames, proxied assets, fonts, and CSS;
• driver and viewer roles for a small trusted group;
• an optional persistent browser profile.

The default Compose path runs one browsing session. Compatibility still varies by site, especially around DRM, unusual browser APIs, hostile CSP combinations, and cross-origin media.

Read Architecture for the full data flow and Troubleshooting when a page diverges.

Deployment

Keep the application port on loopback and put HTTPS in front of it. CDP must remain private. Use stable signing secrets, install an outbound policy that keeps Chromium away from private infrastructure, and enable profile persistence only when you intend to retain browser credentials.

The exact settings and production boundary live in:

• Configuration
• Deployment
• Security model

Development

Use Node 22.23.1 and pnpm 9.15.9.

corepack enable
pnpm install --frozen-lockfile
CHROME_PATH=/usr/bin/google-chrome pnpm run ci

pnpm run ci builds the workspace, checks types and formatting, runs the unit suite, and exercises the browser mirror against real Chromium.

See Contributing for the working rules.

License

Apache License 2.0. See LICENSE, NOTICE, and third-party notices.