{
  "markdown": "<p align=\"center\">\n  <img src=\"extension/icons/icon128.png\" width=\"96\" height=\"96\" alt=\"Browser Relay logo\">\n</p>\n\n<h1 align=\"center\">Browser Relay</h1>\n\n<p align=\"center\">\n  Let AI agents use the same Chrome browser you use every day.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@linsoai/browser-relay\"><img src=\"https://img.shields.io/npm/v/@linsoai/browser-relay.svg\" alt=\"npm version\"></a>\n  <a href=\"https://www.npmjs.com/package/@linsoai/browser-relay\"><img src=\"https://img.shields.io/npm/dm/@linsoai/browser-relay.svg\" alt=\"npm downloads\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-green.svg\" alt=\"MIT License\"></a>\n  <img src=\"https://img.shields.io/badge/agent-Skill%20%2B%20CLI-blue\" alt=\"Agent Skill and CLI\">\n  <img src=\"https://img.shields.io/badge/remote-multi--machine-7c3aed\" alt=\"Remote multi-machine control\">\n  <img src=\"https://img.shields.io/badge/local--first-127.0.0.1-111827\" alt=\"Local first\">\n</p>\n\n<p align=\"center\">\n  <a href=\"#quick-start\">Quick Start</a>\n  ·\n  <a href=\"#agent-friendly-by-default\">Agent Skill</a>\n  ·\n  <a href=\"#cli\">CLI</a>\n  ·\n  <a href=\"#remote-control-remote-relay\">Remote</a>\n  ·\n  <a href=\"https://github.com/reliefeai/browser-relay/blob/main/docs/README.zh-CN.md\">中文</a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/reliefeai/browser-relay/blob/main/docs/assets/browser-relay-mobile-to-office.mp4\">\n    <img src=\"https://raw.githubusercontent.com/reliefeai/browser-relay/main/docs/assets/browser-relay-mobile-to-office.gif\" width=\"960\" alt=\"Illustrated Browser Relay workflow: an agent on a phone uses the Skill and CLI to operate a mock internal dashboard in the existing Chrome browser on an office machine\">\n  </a>\n</p>\n\n<p align=\"center\"><sub>Illustrated workflow with mock data and no real credentials. Click the animation for the MP4 version.</sub></p>\n\nBrowser 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.\n\nUse 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.\n\n## Real Chrome, not a throwaway profile\n\nMost 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.\n\nBrowser Relay is that missing layer:\n\n- **Your actual Chrome session** — cookies, localStorage, extensions, and login state, shared as-is.\n- **No pop-up automation browser** — it never spawns a separate window or opens tabs behind your back; navigation reuses an attached tab.\n- **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.\n- **Agent-first** — install the bundled Skill so Claude Code, Codex, Cursor, Windsurf, and other agents know when and how to use the inspectable CLI.\n- **Local-first boundary** — the relay binds to `127.0.0.1` by default.\n\n## Provenance\n\nBased on [chengyixu/openclaw-browser-relay](https://github.com/chengyixu/openclaw-browser-relay), with auto-attach behavior inspired by [blakesabatinelli/openclaw-chrome-relay](https://github.com/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.\n\n## Architecture\n\n```text\nLocal\n  AI Agent ──Skill + CLI──▶ Relay server (Node, 127.0.0.1)\n                                        │ WebSocket\n                                        ▼\n                                 Chrome extension ──chrome.debugger / CDP──▶ your Chrome tabs\n\nRemote (Remote Relay)\n  AI Agent ──HTTPS──▶ public relay (relay.linso.ai) ◀──WSS── Chrome extension ──▶ your Chrome tabs\n```\n\n**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.\n\n**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).\n\n## Quick Start\n\nUse Browser Relay in four steps. You need desktop Chrome plus Node.js/npm. The Chrome extension is loaded manually from its installed directory.\n\n### 1. Install\n\n```bash\nnpm install -g @linsoai/browser-relay\n```\n\nThe package attempts to register a user-level background service. If your environment has no supported service manager, the verification step below gives the exact foreground command instead of failing with a stack trace.\n\n### 2. Load the Chrome extension\n\nPrint the extension directory:\n\n```bash\nbrowser-relay path\n```\n\nThen open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the `extension` directory printed by `browser-relay path`.\n\n### 3. Verify the browser connection\n\nRun one complete read-only diagnosis, then list the attached tabs:\n\n```bash\nbrowser-relay doctor\nbrowser-relay tabs\n```\n\n`doctor` should report a healthy relay and connected extension. `tabs` should print at least one tab ID, title, and URL:\n\n```text\nt_A7k2Pm9QxL    Example Domain    https://example.com/\n```\n\nIf `doctor` says the service manager is unavailable, start the relay in another terminal and keep it running:\n\n```bash\nbrowser-relay\n```\n\nThen retry `browser-relay doctor`. If the relay is healthy but no tabs appear, reload the unpacked extension and retry `browser-relay tabs`. `doctor` never installs, restarts, or changes anything; add `--json` for automation.\n\n<details>\n<summary>Background service, updates, and platform notes</summary>\n\nThe global install uses launchd on macOS, systemd-user on Linux, and a current-user Task Scheduler task on Windows. The service starts when you sign in. The Windows task uses your existing interactive login token with least privilege: it does not store a password, elevate itself, or run as SYSTEM. Organization policy can still block standard-user task registration.\n\n`browser-relay install` safely refreshes a Browser Relay-owned service definition, starts it, and verifies the HTTP endpoint and installed version. Run it after an nvm upgrade or when `doctor` recommends it. It refuses to overwrite a same-name Windows task without Browser Relay's ownership marker. If a managed environment has no usable service manager, foreground mode (`browser-relay`) remains available.\n\nUpgrade with `browser-relay update`. It installs `@linsoai/browser-relay@latest` globally, attempts to refresh the service, and prints a status check; the extension reloads itself on its next relay reconnect (within about 30 seconds).\n\n</details>\n\n### 4. Install the Agent Skill and run the first task\n\nBrowser Relay ships with an agent-friendly Skill. Choose the Agent explicitly so installation never opens an interactive selector:\n\n```bash\nbrowser-relay skill install --agent codex\n\n# Claude Code, or both agents at once:\nbrowser-relay skill install --agent claude-code\nbrowser-relay skill install --agent codex claude-code\n```\n\nThe command uses the standard `skills` CLI non-interactively, then reads every target `SKILL.md` back to verify it. Use `--agent universal` for agents that consume the standard `~/.agents/skills` directory, `browser-relay skill path` to inspect the bundled source, or plain `browser-relay skill` to print the legacy Codex install command. After installation, your agent can operate your own browser without opening a separate automation browser.\n\nGive the agent a small read-only task first:\n\n```text\nUse Browser Relay to tell me the title and URL of my current Chrome tab. Do not navigate.\n```\n\nThe first successful response proves the full path works: Agent Skill → CLI → relay → extension → your existing Chrome tab.\n\nIf Browser Relay solves a workflow you actually have, starring the repository helps other agent builders find it.\n\n## Agent Friendly by Default\n\nBrowser Relay is designed to be comfortable for agents, not just low-level automation scripts.\n\n- The included Skill tells agents when to use Browser Relay and how to interact safely.\n- Page snapshots are annotated with links, buttons, inputs, and other interactive elements so agents can plan before acting.\n- Actions target existing attached tabs, keeping the user's browser context visible and predictable.\n- Stable CSS waits let agents wait for an element to attach or become visible instead of guessing with fixed sleeps.\n- Console and network capture record `console.*`, page exceptions, log entries, and request/response activity for debugging real-page behavior.\n\n## CLI\n\nThe CLI is the primary interface. For agents that can run shell commands, it is faster and less error-prone than hand-writing `curl` JSON:\n\n```bash\nbrowser-relay tabs\nbrowser-relay console --tab t_A7k2Pm9QxL --limit 50\nbrowser-relay network --tab t_A7k2Pm9QxL --type response --status 500\nbrowser-relay snapshot --tab t_A7k2Pm9QxL --max-length 20000\nbrowser-relay wait 'button[type=submit]' --state visible --timeout 10000 --tab t_A7k2Pm9QxL\nbrowser-relay click 'button[type=submit]' --tab t_A7k2Pm9QxL\nbrowser-relay type 'hello world' --selector 'input[name=q]' --clear --submit\nbrowser-relay key Control+L\nbrowser-relay scroll down --amount 1000\nbrowser-relay screenshot /tmp/page.png --full-page\nbrowser-relay eval 'document.title'\n```\n\nFor long text or JavaScript, avoid shell escaping by reading from stdin:\n\n```bash\nprintf 'hello\\nworld' | browser-relay type --selector textarea --stdin\nbrowser-relay eval --stdin < script.js\n```\n\nAll 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.\n\n### Remote control (Remote Relay)\n\nTo 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.\n\nTurning it on mints a secret **Device ID** — treat it like a password. Pass it to the same CLI commands from anywhere:\n\n```bash\nbrowser-relay tabs --remote-device-id br-xxxx\nbrowser-relay eval \"location.href\" --remote-device-id br-xxxx\n\n# Save an alias once so you don't retype the id (remote ls / rm to manage):\nbrowser-relay remote add mymac br-xxxx\nbrowser-relay tabs --remote mymac\n```\n\nSaved remote IDs are credentials. On POSIX systems Browser Relay stores them in\n`~/.browser-relay/remotes.json` and enforces `0700` on the directory and `0600` on\nthe file, including tightening permissions created by older versions.\n`browser-relay remote ls`, including `--json`, returns only `(redacted)` IDs; it never\nprints the stored capability.\n\n**Run your own relay** instead of the hosted one — one click deploys the Worker in `hub/` to your own Cloudflare account:\n\n[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/reliefeai/browser-relay/tree/main/hub)\n\nThe 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.\n\nThe `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`.\n\n### CLI reference\n\n```bash\nbrowser-relay            # Run the relay server in the foreground\nbrowser-relay start      # Start the background service\nbrowser-relay stop       # Stop the background service\nbrowser-relay restart    # Restart the background service\nbrowser-relay fix        # Restart and clear stale session state (when tabs won't connect)\nbrowser-relay update     # Update the global package and refresh the service\nbrowser-relay status     # Show service state and HTTP health\nbrowser-relay doctor     # Run a complete read-only installation diagnosis\nbrowser-relay logs       # Follow the platform service logs\nbrowser-relay path       # Print the Chrome extension directory\nbrowser-relay skill install --agent codex # Install/update and verify the Agent Skill\nbrowser-relay skill path                  # Print the bundled Skill directory\nbrowser-relay install    # Register the background service\nbrowser-relay uninstall  # Unregister the background service\n\nbrowser-relay tabs       # List attached browser tabs\nbrowser-relay console    # Print captured console/page errors\nbrowser-relay network    # Print captured network requests/responses/failures\nbrowser-relay snapshot   # Print annotated page text\nbrowser-relay wait       # Wait for a CSS selector to attach or become visible\nbrowser-relay click      # Click an element by CSS selector\nbrowser-relay type       # Type text into the page\nbrowser-relay key        # Press a key or shortcut\nbrowser-relay scroll     # Scroll the page\nbrowser-relay screenshot # Save a PNG screenshot\nbrowser-relay eval       # Evaluate JavaScript in the page\nbrowser-relay download   # Print src/href for an element\nbrowser-relay download-start # Start a Chrome download\nbrowser-relay downloads      # List Chrome downloads and events\nbrowser-relay remote     # Manage remote aliases (add / ls / rm)\nbrowser-relay api-help   # Show browser command examples\n```\n\n## MCP\n\nAfter installing the npm package, use `browser-relay-mcp` directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"browser\": {\n      \"command\": \"browser-relay-mcp\",\n      \"env\": {\n        \"BROWSER_RELAY_URL\": \"http://127.0.0.1:18795\"\n      }\n    }\n  }\n}\n```\n\nThe MCP server exposes high-level tools such as `browser_tabs`, `browser_snapshot`, `browser_wait`, `browser_click`, `browser_type`, `browser_key`, and `browser_screenshot`.\n\n## HTTP API\n\nThe HTTP API is the stable integration surface for code and custom tools. For interactive agent work, prefer the CLI above.\n\nErrors use a structured shape across HTTP, CLI `--json`, and MCP tool errors:\n\n```json\n{ \"ok\": false, \"code\": \"invalid_request\", \"error\": \"url is required\", \"message\": \"url is required\", \"status\": 400, \"retryable\": false }\n```\n\n```bash\n# List attached tabs\ncurl http://127.0.0.1:18795/api/tabs\n\n# Take a text snapshot of a page\ncurl \"http://127.0.0.1:18795/api/snapshot?tabId=t_A7k2Pm9QxL\"\n\n# Wait until an element is visible (attached is also supported)\ncurl -X POST http://127.0.0.1:18795/api/wait \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tabId\":\"t_A7k2Pm9QxL\",\"selector\":\"button.submit\",\"state\":\"visible\",\"timeoutMs\":10000}'\n\n# Read captured console/page errors\ncurl \"http://127.0.0.1:18795/api/console?tabId=t_A7k2Pm9QxL&limit=50\"\n\n# Read captured network activity (sensitive headers are redacted)\ncurl \"http://127.0.0.1:18795/api/network?tabId=t_A7k2Pm9QxL&type=response&status=500\"\n\n# Click an element\ncurl -X POST http://127.0.0.1:18795/api/click \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tabId\":\"t_A7k2Pm9QxL\",\"selector\":\"button.submit\"}'\n```\n\n| Endpoint | Method | Description |\n| --- | --- | --- |\n| `/` | GET/HEAD | Health check |\n| `/api/debug` | GET | Server diagnostics |\n| `/api/tabs` | GET | List attached tabs |\n| `/api/console` | GET | Read captured console/page error entries |\n| `/api/console/clear` | POST | Clear captured console entries |\n| `/api/network` | GET | Read captured Network.* request/response/failure entries |\n| `/api/network/clear` | POST | Clear captured network entries |\n| `/api/navigate` | POST | Navigate an attached tab |\n| `/api/snapshot` | GET | Get annotated text or raw HTML |\n| `/api/wait` | POST | Wait for a CSS selector to attach or become visible |\n| `/api/click` | POST | Click an element by CSS selector |\n| `/api/type` | POST | Type into an input |\n| `/api/key` | POST | Press a key or keyboard shortcut |\n| `/api/scroll` | POST | Scroll the page |\n| `/api/screenshot` | GET/POST | Capture a PNG screenshot; full-page mode returns capture strategy/size metadata |\n| `/api/eval` | POST | Evaluate JavaScript in the page |\n| `/api/download` | POST | Extract an element URL |\n| `/api/download/start` | POST | Start a real Chrome download from a URL |\n| `/api/downloads` | GET | List Chrome downloads and recent download events |\n| `/api/downloads/clear` | POST | Clear captured download events |\n\nReal Chrome downloads require the extension's `downloads` permission. After upgrading from an older Browser Relay version, reload the unpacked extension in `chrome://extensions`.\n\nThe same endpoints are reachable remotely: a CLI running with `--remote-device-id` sends them through the public relay to the browser.\n\n## Configuration\n\n| Environment variable | Default | Description |\n| --- | --- | --- |\n| `BROWSER_RELAY_URL` | `http://127.0.0.1:18795` | Relay base URL used by CLI browser commands and MCP |\n| `BROWSER_RELAY_HOST` | `127.0.0.1` | HTTP and WebSocket bind address |\n| `BROWSER_RELAY_PORT` | `18795` | HTTP and WebSocket port |\n| `BROWSER_RELAY_REMOTE_DEVICE_ID` | — | Remote Device ID (or alias) used when no `--remote-device-id` flag is passed |\n| `BROWSER_RELAY_REMOTE_HOST` | `https://relay.linso.ai` | Public relay URL for remote commands |\n\nThe Chrome extension port can be changed from the extension Options page.\n\nService files:\n\n```text\nmacOS: ~/Library/LaunchAgents/org.browser-relay.service.plist\nLinux: ~/.config/systemd/user/browser-relay.service\nWindows task: BrowserRelay\nWindows definition: %LOCALAPPDATA%\\BrowserRelay\\task.xml\n```\n\nLogs:\n\n```text\nmacOS: /tmp/browser-relay.log, /tmp/browser-relay.error.log\nLinux: journalctl --user -u browser-relay\nWindows: %LOCALAPPDATA%\\BrowserRelay\\logs\\browser-relay.log\n         %LOCALAPPDATA%\\BrowserRelay\\logs\\browser-relay.error.log\n```\n\nOn Windows, `uninstall` removes only the Browser Relay scheduled task and its generated XML definition. It preserves logs for diagnosis and never kills an unrelated process that happens to use port `18795`.\n\n### Hiding the \"debugging this browser\" infobar\n\nWhenever the extension has a debugger attached, Chrome shows a mandatory\n`\"Browser Relay\" started debugging this browser` bar at the top of the page.\nNo extension API can remove it — it is Chrome's built-in anti-abuse warning.\n\nTwo ways to deal with it:\n\n- **Automatic (default):** the extension soft-detaches idle tabs after 10 min, so\n  the bar disappears on its own while you're not using it and re-attaches on the\n  next command. Nothing to configure.\n- **Remove it entirely:** launch Chrome with the `--silent-debugger-extension-api`\n  flag, which suppresses the bar for the debugger extension API. You must fully\n  quit Chrome first (`open --args` only passes flags to a cold start):\n\n  ```bash\n  # macOS\n  osascript -e 'quit app \"Google Chrome\"'\n  open -a \"Google Chrome\" --args --silent-debugger-extension-api\n  ```\n\n  To make it stick, always launch Chrome this way (e.g. a shell alias or a\n  `.command` launcher) — a normal Dock click won't carry the flag.\n\n  Trade-off: this weakens a security protection — *any* extension with the\n  `debugger` permission can then silently attach without warning. Fine for\n  personal use as long as you understand what it disables.\n\n## Development\n\n```bash\nnpm install\nnpm start\nnpm run mcp\nnpm test\n```\n\nLoad the local `extension/` directory from `chrome://extensions` in Developer mode.\n\n## Security\n\n- The extension uses Chrome's `debugger` permission. Install only versions you trust.\n- The relay binds to `127.0.0.1` by default. Do not expose it to the public internet.\n- Remote Relay never opens a port: the browser connects out to the public relay, which only holds a hash of your Device ID secret in memory. Treat the Device ID like a password; anyone with it can control the browser while Remote Relay is on.\n- Browser Relay gives agents access to the same browser state you have, so treat enabled agents as trusted local software.\n\n## License\n\nMIT\n",
  "bytes": 20671,
  "sha": "1c4eb3c01f885512c177c41f686b2b606934ef637fd8f13056347b5e0d1fed63",
  "repo_slug": "reliefeai/browser-relay",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_reliefeai_browser_relay_8b3f3fb9/readme"
}