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.

Everything Kilogent-specific lives in files named kilogent-*:

The rule that keeps this fork alive: never edit the core. executor.js, page-scripts.js and connection.js come from upstream untouched, 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

⚠️ sw.js and popup.js are the two files that do NOT yet obey that rule — Kilogent's transport was written into them in place rather than beside them, so they will conflict on every upstream merge until the core/provider split lands. That split is the next piece of work.

📖 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.

Related MCP server: kilo-computer-use

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  (Aso Dara 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…

Packages

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+

• Google Chrome

• cloudflared on the VM (brew install cloudflared / apt) — publishes the WebSocket face

• A shared token: openssl rand -hex 32 — the same value goes on the VM and in the extension popup

• (only for the standalone packages/agent) a Gemini API key (GEMINI_API_KEY), or set LLM_PROVIDER=anthropic + ANTHROPIC_API_KEY

Quick start

Three steps: run the bridge on the VM, load the extension in Chrome, verify. About ten minutes end to end.

npm install
npm run build

1 · VM — run the bridge

BRIDGE_ACCESS_TOKEN=<token> BRIDGE_MCP_TOKEN=<mcp-token> MCP_PORT=3000 WS_PORT=3002 \
  node packages/bridge-server/dist/index.js
# or under pm2:
BRIDGE_ACCESS_TOKEN=<token> BRIDGE_MCP_TOKEN=<mcp-token> pm2 start packages/bridge-server/dist/index.js --name rbm-bridge

Publish the WS face with cloudflared and point the VM's agent at the MCP face (http://localhost:3000/mcp). Full ingress config and DNS notes are in BRIDGE-SETUP.md.

2 · Machine — load the extension (one dedicated profile)

1. Create a dedicated Chrome profile for the agent (e.g. "Aso Dara"), 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 and set Agent URL (wss://…/rbm-ws) + Access Token (the token from step 1) → Save & Connect. Status should read Connected to agent.

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 · Verify end-to-end

# on the VM
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"

/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.

Or drive the whole path with the standalone agent's no-API-key check:

npm run smoke --workspace=packages/agent

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.