Browser Relay lets an AI agent join the Chrome browser you already use through an agent-native Skill + CLI. It does not launch a blank automation profile, keep pulling another browser window to the foreground, or make you log in again. You and the agent work in the same everyday browser — locally or across multiple machines.
Use it when the task lives in a browser that already has the right login, extensions, device trust, or network access: operate your desktop browser from an agent on your phone, reach an internal system through the already-authenticated browser on your work computer, or let one agent work across browsers on several machines.
Real Chrome, not a throwaway profile
Most browser automation spins up a fresh, empty browser profile. That is fine for testing, but useless for agents that need your authenticated web apps — SaaS dashboards, admin panels, internal tools, documents, private sessions — where a headless browser or a fresh profile simply is not logged in.
Browser Relay is that missing layer:
- Your actual Chrome session — cookies, localStorage, extensions, and login state, shared as-is.
- No pop-up automation browser — it never spawns a separate window or opens tabs behind your back; navigation reuses an attached tab.
- Local or remote — one agent can drive browsers on this machine or several other machines through an outbound relay connection, with no public browser port exposed.
- Agent-first — install the bundled Skill so Claude Code, Codex, Cursor, Windsurf, and other agents know when and how to use the inspectable CLI.
- Local-first boundary — the relay binds to
127.0.0.1by default.
Provenance
Based on chengyixu/openclaw-browser-relay, with auto-attach behavior inspired by blakesabatinelli/openclaw-chrome-relay. Repackaged as a general-purpose local browser bridge for AI agents, without the OpenClaw-specific gateway, token auth, or platform bindings.
Architecture
Local
AI Agent ──Skill + CLI──▶ Relay server (Node, 127.0.0.1)
│ WebSocket
▼
Chrome extension ──chrome.debugger / CDP──▶ your Chrome tabs
Remote (Remote Relay)
AI Agent ──HTTPS──▶ public relay (relay.linso.ai) ◀──WSS── Chrome extension ──▶ your Chrome tabs
Local mode is the default: the agent talks to a relay server on 127.0.0.1, which forwards Chrome DevTools Protocol commands to the extension.
Remote mode exposes nothing. When you turn on Remote Relay, the extension connects out to a public relay service; a remote CLI reaches that same service, which routes each command down to your browser over the existing connection — no open ports, no local server on the network. Use the default hosted relay, or run your own on Cloudflare in one click (see below).
Quick Start
Use Browser Relay in three steps.
1. Install
npm install -g @linsoai/browser-relay
browser-relay status
On macOS and Linux, the global install registers a user-level background service through launchd or systemd-user. The service starts on login and restarts on crash.
If the service is not running yet:
browser-relay start
2. Load the Chrome extension
Print the extension directory:
browser-relay path
Then open chrome://extensions, enable Developer mode, click Load unpacked, and select the extension directory printed by browser-relay path.
Upgrade with browser-relay update. It installs @linsoai/browser-relay@latest globally, refreshes the background service, and prints a status check; the extension reloads itself the next time it reconnects (within ~30 seconds).
3. Install the Agent Skill
Browser Relay ships with an agent-friendly Skill. Print the install command:
browser-relay skill
Then run the printed npx skills ... command and choose the agent to install it into, or run it directly with $(browser-relay skill). After that, your agent can operate your own browser without opening a separate automation browser.
Agent Friendly by Default
Browser Relay is designed to be comfortable for agents, not just low-level automation scripts.
- The included Skill tells agents when to use Browser Relay and how to interact safely.
- Page snapshots are annotated with links, buttons, inputs, and other interactive elements so agents can plan before acting.
- Actions target existing attached tabs, keeping the user's browser context visible and predictable.
- Console and network capture record
console.*, page exceptions, log entries, and request/response activity for debugging real-page behavior.
CLI
The CLI is the primary interface. For agents that can run shell commands, it is faster and less error-prone than hand-writing curl JSON:
browser-relay tabs
browser-relay console --tab ABC123 --limit 50
browser-relay network --tab ABC123 --type response --status 500
browser-relay snapshot --tab ABC123 --max-length 20000
browser-relay click 'button[type=submit]' --tab ABC123
browser-relay type 'hello world' --selector 'input[name=q]' --clear --submit
browser-relay key Control+L
browser-relay scroll down --amount 1000
browser-relay screenshot /tmp/page.png --full-page
browser-relay eval 'document.title'
For long text or JavaScript, avoid shell escaping by reading from stdin:
printf 'hello\nworld' | browser-relay type --selector textarea --stdin
browser-relay eval --stdin < script.js
All browser commands accept --json for the raw API response and --tab <id> to target a specific tab. When --json is used, a failed command prints the structured error payload and exits non-zero.
Remote control (Remote Relay)
To drive this browser from another machine — a CI box, a remote agent, a different network — turn on Remote Relay in the extension's Options page. The browser connects out to a public relay service (the hosted relay.linso.ai by default); nothing listens on a public port and no local server is exposed.
Turning it on mints a secret Device ID — treat it like a password. Pass it to the same CLI commands from anywhere:
browser-relay tabs --remote-device-id br-xxxx
browser-relay eval "location.href" --remote-device-id br-xxxx
# Save an alias once so you don't retype the id (remote ls / rm to manage):
browser-relay remote add mymac br-xxxx
browser-relay tabs --remote mymac
Run your own relay instead of the hosted one — one click deploys the Worker in hub/ to your own Cloudflare account:
The button connects Cloudflare to your GitHub the first time (Workers Builds). Prefer the CLI? git clone, then cd hub && npx wrangler deploy. Either way, put the resulting …workers.dev URL in the Options page's Public relay field.
The remote-device-id is a capability — anyone with it can control this browser while Remote Relay is on. Design notes: docs/remote-control-hub.md.
CLI reference
browser-relay # Run the relay server in the foreground
browser-relay start # Start the background service
browser-relay stop # Stop the background service
browser-relay restart # Restart the background service
browser-relay fix # Restart and clear stale session state (when tabs won't connect)
browser-relay update # Update the global package and refresh the service
browser-relay status # Show service state and HTTP health
browser-relay logs # Tail /tmp/browser-relay.log
browser-relay path # Print the Chrome extension directory
browser-relay skill # Print the Skill install command
browser-relay install # Register the background service
browser-relay uninstall # Unregister the background service
browser-relay tabs # List attached browser tabs
browser-relay console # Print captured console/page errors
browser-relay network # Print captured network requests/responses/failures
browser-relay snapshot # Print annotated page text
browser-relay click # Click an element by CSS selector
browser-relay type # Type text into the page
browser-relay key # Press a key or shortcut
browser-relay scroll # Scroll the page
browser-relay screenshot # Save a PNG screenshot
browser-relay eval # Evaluate JavaScript in the page
browser-relay download # Print src/href for an element
browser-relay download-start # Start a Chrome download
browser-relay downloads