Kilogent Browser

Lend your own Chrome to a Kilogent workspace, so agents can use the sites you are already signed in to. They never see a password, and they never see a tab you opened.

The only thing you install is a Chrome extension. It dials out, so there is nothing to open on your machine — no inbound port, no tunnel, no --remote-debugging flag.

This is a fork, and that is on purpose

Upstream is navidshad/remote-browser-mcp — the open project: the extension core, the relay, and the MCP server. This repository is the Kilogent-branded build of it.

See BRIDGE-SETUP.md to put the agent on a different machine. PRD.md is kept as a historical record of the original design and no longer describes this code.

Everything Kilogent-specific lives in one directory, packages/extension/src/providers/kilogent/:

File	What it does
index.js	the transport itself — what upstream's registry calls
popup.js	the panel — sign-in, workspaces, blocklist
auth.js	signing in, and keeping the session alive
connection.js	the socket to Kilogent's relay
api.js	the browser's own row, written under rules
blocklist.js	the second of the two blocklist levels
config.js	the one URL compiled in, and the storage keys

The rule that keeps this fork alive: never edit the core. executor.js, page-scripts.js and connection.js come from upstream untouched — as do sw.js, providers/registry.js and providers/bridge/ — so git merge upstream/main stays clean. A fix that belongs to everybody goes upstream as a pull request and comes back down; only branding and the Kilogent transport are ours.

git remote add upstream https://github.com/navidshad/remote-browser-mcp.git
git fetch upstream && git merge upstream/main

Neither sw.js nor popup.js conflicts any more. Both used to, on every merge, because the transport and the sign-in UI were written into them — 390 lines where upstream had 69, and 391 where upstream had 177. Upstream grew a seam on both sides, ours moved into the directory above, and the worker and the popup shell are now byte-identical on both sides.

Our whole divergence in code is that one directory, plus one import and one entry in each of providers/index.js and providers/panels.js.

⚠️ popup.html is the small remainder. Its body is upstream's structure — same ids, same mount point — so a structural change merges; what is ours is the heading and the stylesheet, which is what a brand IS. And manifest.json, for the same reason.

📖 MAINTAINING.md is the guide for both jobs: the full update loop (including which files conflict and how to resolve them), and the complete inventory of what a rebrand touches — written from the real Lumi → Kilogent rename, so the three traps in it are ones that actually happened rather than ones that might.

Running it against your own server instead

The self-hosted path is untouched and needs no Kilogent account: point the extension at a bridge you run yourself, with a URL and a shared token. See packages/bridge-server below, and the Advanced section of the popup.

Features

• 🔐 Browse as yourself — the agent works inside your genuine Chrome profile: existing logins, cookies, sessions, extensions, and your home IP. No credential sharing, no re-authentication, no datacenter/bot fingerprint.
• 📡 Outbound-only, token-authenticated — the extension dials out over wss:// and authenticates with a shared token. Zero inbound ports, zero local tunnels, zero debug flags on your machine.
• 🔌 Standard MCP, Playwright-compatible tools — one Streamable-HTTP MCP endpoint with tool names mirroring the official Playwright MCP (browser_navigate, browser_snapshot, browser_click, …). Works out of the box with Claude Code or any MCP client; agents written against Playwright MCP port over almost unchanged.
• 👀 Live activity overlay — a colored ring + status badge appears on the page whenever the agent acts, so you always know what it's doing. It self-clears the moment the agent goes idle.
• ✋ Take over anytime — it's your real browser window; just grab the mouse. An optional per-profile input-lock prevents you from accidentally fighting the agent mid-task, and always self-releases.
• 🤖 Multi-agent, multi-profile — run several Chrome profiles, each dialed into its own bridge. Every MCP session gets its own Chrome tab group, so parallel agents keep their work visually separate and never touch each other's tabs.
• 🧱 Profile-level isolation — a Chrome extension can only act within its own profile. Install it in one dedicated profile and the agent physically cannot reach your personal browsing.
• 🧪 Snapshot-driven control — the agent reads pages as accessibility trees with stable [ref=eNN] element ids, then clicks/types by ref. Faster and more reliable than pixel-hunting screenshots (screenshots are there too when needed).
• 🩺 Self-healing & observable — WebSocket heartbeat + chrome.alarms keepalive survive MV3 service-worker eviction, reconnect with backoff, and re-attach the debugger lazily. /health, bridge_ping, and check_local_status tell the agent whether a human/browser is actually there. Idle sessions are reaped automatically.
• 🪶 Tiny footprint — no Playwright install, no Node process, no daemon on your machine. One unpacked MV3 extension; everything else lives on the VM.

How it works

There are two halves that meet over an authenticated WebSocket:

• On the VM — packages/bridge-server exposes browser control to the agent as MCP and relays each command to the browser. It has two faces:
  • an MCP face on localhost:3000/mcp — the VM's Claude Code (or packages/agent) connects here and calls browser_* tools. Requires Authorization: Bearer $BRIDGE_MCP_TOKEN;
  • a WebSocket face on localhost:3002 — the extension dials in and authenticates with a shared token. cloudflared running on the VM publishes this face at a wss:// URL.
• On your machine — the packages/extension MV3 extension runs in a dedicated Chrome profile, dials out to that wss:// URL, and drives a real tab with chrome.debugger (CDP).

   ┌──────────────────────── CLOUD VM ────────────────────────┐        ┌───────────── YOUR MACHINE ─────────────┐
   │  AI Agent  ──MCP──▶  bridge-server                        │        │  MV3 extension  (agent profile)        │
   │  (Claude Code /       ├─ MCP face  localhost:3000/mcp     │        │    │                                    │
   │   packages/agent)     └─ WS  face  localhost:3002 ◀───────┼── wss ─┼────┘  dials OUT, token-authenticated   │
   │                          published by cloudflared         │        │    chrome.debugger / CDP  ──▶  a tab   │
   └───────────────────────────────────────────────────────────┘        └────────────────────────────────────────┘
                                        ▲                                          nothing inbound on your machine
                                        └──────── agent never touches localhost; always over the network ─────────

Browser tool names mirror the official Playwright MCP, so an agent (or contract) written against Playwright MCP works with almost no changes.

Why not just…

Alternative	What goes wrong
A headless browser on the VM	Fresh profile with no logins, a datacenter IP, and a bot fingerprint — captchas, blocks, and 2FA prompts everywhere.
Chrome with --remote-debugging-port	Chrome 136+ blocks it on your default profile, so you lose your real logins anyway — and you're running your browser with an open debug port.
Tunneling into your machine	Inbound access to your laptop (tunnel daemons, port forwarding, access policies) just to reach a browser. Here the browser dials out instead — there is nothing to reach.
Sharing credentials with the agent	Passwords and 2FA secrets in an agent's context. Here the agent gets a browser that is already signed in and never sees a credential.

Packages

Path	What it is
packages/bridge-server	VM-side bridge. MCP browser tools ⇄ WebSocket to the extension, with token auth, /health, and per-session tab tracking. Exposes browser_*, check_local_status, and bridge_ping. This is the self-host path, and the only server in this repo — if you are running this for yourself, this is the one you want. A hosted service that wants its own transport adds one under packages/extension/src/providers/; see "Adding your own transport" below. Kilogent mode does not use it — that path goes to the relay below.
packages/extension	The MV3 Chrome extension. Popup for Agent URL + token, a service worker holding one outbound WS per profile (heartbeat + chrome.alarms keepalive + reconnect backoff), and a chrome.debugger executor.
packages/relay	Side 2 of the hosted path. One process holding one WebSocket per connected browser, so a product can address a Chrome on somebody's laptop. Presence and dispatch only — it is not an authorization boundary, and who a browser is comes from a pluggable auth provider (ticket or token). Published to npm as remote-browser-relay; npm i -g remote-browser-relay for the release, @dev for the pre-release.
packages/agent	A standalone terminal agent — a stand-in for the VM's real client. Connects to the bridge and runs a tool-use loop. LLM is pluggable (src/llm) — Gemini by default, Anthropic optional — with a no-API-key smoke test (npm run smoke --workspace=packages/agent, against a running bridge).

Browser tools

All exposed on the one bridge MCP endpoint, mirroring Playwright MCP names:

browser_navigate · browser_snapshot · browser_click · browser_type · browser_press_key · browser_take_screenshot · browser_wait_for · browser_tab_list · browser_tab_new · browser_tab_select · browser_tab_close · check_local_status · bridge_ping

browser_snapshot returns an accessibility tree whose interactable elements are tagged with [ref=eNN] ids; you pass those refs to browser_click / browser_type. Refs are only valid for that tab's latest snapshot, so re-snapshot after navigation or DOM changes.

Prerequisites

• Node.js 22+ (.nvmrc pins 22.22.3)
• Google Chrome
• (only if the agent runs on a different machine) cloudflared or any other way to publish one WebSocket port — see BRIDGE-SETUP.md. Not needed to try this.
• (only for the standalone packages/agent) a Gemini API key (GEMINI_API_KEY), or set LLM_PROVIDER=anthropic + ANTHROPIC_API_KEY

Quick start

Start on one machine. The agent and the browser can be on the same box, and everything below works with no VM, no tunnel and no DNS. Put it on a VM once you have watched it drive your Chrome — that is BRIDGE-SETUP.md, and it changes one URL.

git clone https://github.com/navidshad/remote-browser-mcp
cd remote-browser-mcp
npm install
npm run build

1 · Run the bridge

Two tokens, and they must differ — the bridge refuses to start otherwise. They authenticate two different parties: the extension to the WebSocket face, the agent to the MCP face.

export BRIDGE_ACCESS_TOKEN=$(openssl rand -hex 32)
export BRIDGE_MCP_TOKEN=$(openssl rand -hex 32)
node packages/bridge-server/dist/index.js
# MCP face → http://127.0.0.1:3000/mcp   (loopback)
# WS  face → ws://0.0.0.0:3002           (the extension dials in here)

2 · Load the extension, in one dedicated profile

1. Create a dedicated Chrome profile for the agent, ideally an account-less local profile so Chrome sync can't copy the extension into or out of it.
2. chrome://extensions → Developer mode → Load unpacked → select packages/extension/. Install it in only this profile, and turn off Extensions sync — that isolation is what keeps the agent off your other profiles.
3. Open the popup → + Add profile. Agent URL is ws://localhost:3002 on one machine (wss://… once it is behind a tunnel); Access Token is your BRIDGE_ACCESS_TOKEN. Press Save. The status line should read Connected.
4. Keep a window of that profile open whenever the agent may browse — background is fine, focus is not required. The first command attaches chrome.debugger and shows Chrome's "…started debugging this browser" bar; leave it in place.

3 · Point an agent at it

claude mcp add --transport http browser http://127.0.0.1:3000/mcp \
  --header "Authorization: Bearer $BRIDGE_MCP_TOKEN"
claude mcp list      # browser → ✓ Connected

Then ask it to open a page. You should watch it happen in your own window.

Verify

Two useful checks, and they answer different questions.

npm run test:mock    # the whole path — real bridge, real Executor, real MCP clients, mocked Chrome

That needs nothing running and no tokens: it spawns its own bridge and proves the server half works on this machine. If it passes and your popup still will not connect, the problem is the extension, the profile or the token — not the build.

curl -s localhost:3000/health          # → {"status":"ok",…} — liveness, no credential needed
curl -s localhost:3000/status -H "Authorization: Bearer $BRIDGE_MCP_TOKEN"   # → "extensionConnected":true
BRIDGE_MCP_TOKEN=$BRIDGE_MCP_TOKEN node packages/bridge-server/dist/test-client.js   # bridge_ping → "pong"

Those ask the bridge you are actually running whether your Chrome has arrived.

/health is deliberately thin. It used to report whether a browser was attached, how many tabs it held and which sessions were live — a description of a specific person's Chrome, served to anyone who could reach the port. That moved to /status, behind the token; /health stays anonymous because a tunnel health check has no credential.

Releases

One release per merge to main, covering every package. A release here is a snapshot of the repo: it always states where all packages stand, so you can tell which extension goes with which relay. The extension zip is attached every time, even when the change was elsewhere — the latest release must always be somewhere you can download a working extension from.

What is skipped is the publishing, not the release: scripts/resolve-versions.mjs path-filters each package independently, so a relay-only change does not republish an identical extension. If nothing changed anywhere, no release is cut.

Package	Where it goes	How to get it
Chrome extension	attached to the GitHub Release	download, unzip, load unpacked
remote-browser-relay	npm	npm i -g remote-browser-relay

dev publishes the relay as a prerelease on npm's dev tag (npm i -g remote-browser-relay@dev) and cuts no GitHub Release — a pre-release is for whoever asked for it by name.

npm test              # everything CI gates on — one command, same result
npm run versions      # what the next release would be, and why

One workflow run per merge. CI runs on pull requests and gates the merge; Release runs on a push to main and decides what ships. They used to both run on main, running the same suite twice against the same commit.

npm test runs exactly what CI gates on, and npm run test:ci-parity proves it by reading both files — so a step added to ci.yml and not to npm test fails immediately, rather than the next time somebody trusts a green laptop.

The workflow is four jobs, not four files, and that is deliberate. A release has to list where all packages stand, so something must see every outcome at once — across separate workflow files that means workflow_run chaining, which reintroduces "which commit is this about" and is where release pipelines quietly ship the wrong thing. Jobs give the same separation with needs doing the coordination:

resolve  ──┬──▶ relay      (npm, only if packages/relay changed)
           ├──▶ extension  (stamp + zip, always)
           └──────────────▶ publish  (one GitHub Release, from both outcomes)

A failure is scoped to its package. A relay publish that fails does not stop the extension being built and released — the release says so instead, in the table. Anything other than an outright success is reported as not published, because a release naming a version npm does not have is worse than a red build.

Versions are derived, never typed

From conventional-commit subjects: feat is a minor, a ! or a BREAKING CHANGE: footer is a major, everything else is a patch. Two rules are load-bearing:

• The path filter decides whether to release; the type only decides how big. Any commit touching a package's own paths releases it. An unrecognised type — chore, ci, refactor, an unparseable subject — falls through to a PATCH rather than to "no release". The conventional way round, where only feat/fix release, means a refactor(relay): that changes the shipped bundle publishes nothing and reports success.
• While the major is 0, a breaking change bumps the MINOR rather than jumping to 1.0.0. Reaching 1.0.0 should be somebody's decision.

Two packages, two boundaries, and the difference is not an inconsistency. The relay's is npm's own gitHead for the published version — it cannot drift from what was actually published, which a tag can. The extension is published to no registry, so an extension-v* git tag is its record, pushed only after the release succeeded.

Development

npm run test:mock       # bridge round-trip against a fake-extension WS client
npm run test:profiles   # multi-profile / multi-session harness
npm run build --workspaces

Each package also has dev (tsx watch), start, and typecheck scripts.

Security notes

• Two tokens, and they must differ. BRIDGE_ACCESS_TOKEN authenticates the extension dialling in; BRIDGE_MCP_TOKEN authenticates the agent asking for work. The bridge refuses to start if you set them to the same value — one is typed into a popup on a laptop, the other pasted into an agent config, so they leak through different accidents, and sharing one would mean a leaked agent token also lets the holder impersonate the extension and take over the browser.
• The WS face authenticates in-band, as the first frame — a browser WebSocket cannot send CF-Access-* headers, so the WS hostname must have no Cloudflare Access policy in front of it. Every frame after that handshake is schema-validated and size-bounded (protocol.ts); the socket itself caps one frame at 12 MB.
• The MCP face requires a bearer token and binds to loopback by default. It used to have no authentication at all, on the reasoning that loopback was the boundary — which holds until one tunnel ingress rule exists, and was never a boundary between users on a shared box. Set BRIDGE_BIND_HOST if you genuinely mean to expose it; the token is then the only thing in front of a fully logged-in Chrome.
• Sessions are mandatory. Every call is routed to the tab group its MCP session owns, so a request that names no session is refused rather than being run against a shared "default".
• The extension is the trust boundary. It can drive any tab in its profile via chrome.debugger; keep it in a dedicated profile with only the accounts the agent needs.
• Keepalive is the known risk. MV3 evicts idle service workers; the WS heartbeat keeps it resident and a 1-minute chrome.alarms revives it, re-attaching chrome.debugger lazily on the next command.