Browser Relay

Let AI agents use the same Chrome browser you use every day.

Quick Start · Agent Friendly · HTTP API · 中文

Browser Relay is a local browser-control bridge for AI agents. It connects your existing Chrome session to agents through HTTP API or MCP, so they can read pages, click buttons, type into forms, scroll, take screenshots, and evaluate JavaScript in the same browser where you are already logged in.

No cloud browser. No throwaway automation profile. No surprise browser windows or new tabs. Browser Relay works with the Chrome tabs you already have open, and normal navigation reuses an attached tab instead of launching a separate browser.

Why Browser Relay

Most browser automation tools create a fresh browser profile. That is great for testing, but awkward for agents that need to work with your real web apps, authenticated dashboards, SaaS tools, admin panels, documents, or private sessions.

Browser Relay is built for that missing layer:

Same browser as the user: agents share your real Chrome session, including cookies, localStorage, extensions, and login state.
No pop-up automation browser: it does not spawn a separate Chrome window or create temporary tabs behind your back.
Agent-first interface: use the included Skill, MCP server, or plain HTTP API.
Local-first security boundary: the relay binds to 127.0.0.1 by default.
Universal integration: works with Claude, Claude Code, Cursor, Windsurf, custom agents, scripts, and tools that can call HTTP or MCP.

Provenance

This project is based on source code from chengyixu/openclaw-browser-relay, with architecture and auto-attach behavior inspired by blakesabatinelli/openclaw-chrome-relay.

This distribution removes OpenClaw-specific gateway handshakes, token authentication, and platform bindings, and repackages the relay as a general-purpose local browser bridge for AI agents.

Architecture

AI Agent
  |
  | HTTP API / MCP
  v
Browser Relay Server (Node.js, localhost)
  |
  | WebSocket
  v
Browser Relay Chrome Extension
  |
  | chrome.debugger / CDP
  v
Your existing Chrome tabs

The relay server listens on 127.0.0.1 by default. The Chrome extension attaches to regular Chrome tabs and forwards Chrome DevTools Protocol commands between the local relay and the browser.

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:

chrome://extensions

Enable Developer mode, click Load unpacked, and select the extension directory printed by browser-relay path.

When upgrading the npm package, Chrome will not automatically reload unpacked extensions. After npm install -g @linsoai/browser-relay@latest, open chrome://extensions and click reload on the Browser Relay extension card.

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 you want to install it into.

You can also run it directly:

$(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.
The MCP server exposes high-level tools such as browser_tabs, browser_snapshot, browser_click, browser_type, and browser_screenshot.
The HTTP API is simple enough for any custom agent or script.
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.

MCP

After installing the npm package, use browser-relay-mcp directly:

{
  "mcpServers": {
    "browser": {
      "command": "browser-relay-mcp",
      "env": {
        "BROWSER_RELAY_URL": "http://127.0.0.1:18795"
      }
    }
  }
}

Browser CLI

For agents that can run shell commands, the CLI is usually faster and less error-prone than hand-writing curl JSON:

browser-relay tabs
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 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.

Agent guidance: prefer the CLI for browser interaction. Use the HTTP API when you are writing code, tests, or an integration against Browser Relay, or when a CLI is not available in the environment.

HTTP API

The HTTP API is the stable integration surface for code and custom tools. For interactive agent work, prefer the CLI above.

# List attached tabs
curl http://127.0.0.1:18795/api/tabs

# Take a text snapshot of a page
curl "http://127.0.0.1:18795/api/snapshot?tabId=ABC123"

# Click an element
curl -X POST http://127.0.0.1:18795/api/click \
  -H "Content-Type: application/json" \
  -d '{"tabId":"ABC123","selector":"button.submit"}'

Endpoint	Method	Description
`/`	GET/HEAD	Health check
`/api/debug`	GET	Server diagnostics
`/api/tabs`	GET	List attached tabs
`/api/navigate`	POST	Navigate an attached tab
`/api/snapshot`	GET	Get annotated text or raw HTML
`/api/click`	POST	Click an element by CSS selector
`/api/type`	POST	Type into an input
`/api/scroll`	POST	Scroll the page
`/api/screenshot`	GET/POST	Capture a PNG screenshot
`/api/eval`	POST	Evaluate JavaScript in the page
`/api/download`	POST	Extract an element URL

CLI

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 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 snapshot   # Print annotated page text
browser-relay click      # Click an element by CSS selector
browser-relay type       # Type text into the page
browser-relay screenshot # Save a PNG screenshot
browser-relay eval       # Evaluate JavaScript in the page
browser-relay api-help   # Show browser command examples

Service files:

macOS: ~/Library/LaunchAgents/org.browser-relay.service.plist
Linux: ~/.config/systemd/user/browser-relay.service

Logs:

/tmp/browser-relay.log
/tmp/browser-relay.error.log

Configuration

Environment variable	Default	Description
`BROWSER_RELAY_URL`	`http://127.0.0.1:18795`	Relay base URL used by CLI browser commands and MCP
`BROWSER_RELAY_HOST`	`127.0.0.1`	HTTP and WebSocket bind address
`BROWSER_RELAY_PORT`	`18795`	HTTP and WebSocket port

The Chrome extension port can be changed from the extension Options page.

Development

npm install
npm start
npm run mcp

Load the local extension/ directory from chrome://extensions in Developer mode.

Useful checks:

npm run sync-version
npm run pack:dry-run

Security

The extension uses Chrome's debugger permission. Install only versions you trust.
The relay binds to 127.0.0.1 by default. Do not expose it to the public internet.
If you change the bind address, add your own authentication and network isolation.
Browser Relay gives agents access to the same browser state you have, so treat enabled agents as trusted local software.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/workflows		.github/workflows
extension		extension
scripts		scripts
server		server
skill		skill
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Browser Relay

Why Browser Relay

Provenance

Architecture

Quick Start

1. Install

2. Load the Chrome extension

3. Install the Agent Skill

Agent Friendly by Default

MCP

Browser CLI

HTTP API

CLI

Configuration

Development

Security

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Browser Relay

Why Browser Relay

Provenance

Architecture

Quick Start

1. Install

2. Load the Chrome extension

3. Install the Agent Skill

Agent Friendly by Default

MCP

Browser CLI

HTTP API

CLI

Configuration

Development

Security

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages