ZuBrIQ for Chrome — the agent in your browser
ZuBrIQ for Chrome gives the agent your real browser: open tabs, sites you are signed in to, your extensions. The agent opens its tabs in the background, reads pages, clicks, fills in forms, takes screenshots — and when a human is needed (sign-in, an SMS code, payment), it hands the tab to you and waits.
It works with ZubrCode and ZuBrIQ Desktop, as well as Claude Code, Codex, Cursor, and other agents that can connect MCP servers. Browsers: Chrome, Edge, Brave, Arc, Helium, Vivaldi, Opera, and Chromium.
How it works
Section titled “How it works”Three parts on your computer:
- The extension in the browser — runs commands in tabs through Chrome’s built-in debugger.
- Relay — a small local
zubriq-browseprocess, listening only on127.0.0.1. It starts on its own when the agent needs the browser. - The
zubriq-browseMCP server — through it the agent gets the browser tools. The installer registers it with your agents for you.
Agent → MCP server → relay → extension → tab. The extension and relay pair once and then verify a shared key on every connection, so another program on your computer cannot drive your browser through the relay.
Installation
Section titled “Installation”-
Install the
zubriq-browsecommand:Окно терминала # macOS and Linuxcurl -fsSL https://zubriq.ai/browse.sh | shОкно терминала # Windows (PowerShell)irm https://zubriq.ai/browse.ps1 | iexThe installer puts
zubriq-browseinto~/.local/binand immediately runszubriq-browse install. -
Pick the agents. The ones found on the computer are checked already: space to toggle, Enter to confirm. The installer adds the
zubriq-browseMCP server to them. Running it again only adds — unchecking a box removes nothing. -
Add the extension. The installer opens the “ZuBrIQ for Chrome” page in the Chrome Web Store — click Install. As soon as the extension appears, the installer pairs it with the relay for you; nothing to copy.
-
Restart the agent (or start a new session) so it sees the new MCP server, and ask it, for example: “open zubriq.ai and tell me what’s on the front page”.
To check that everything is in place: zubriq-browse status — it shows the
relay, the extension, and the tabs available to agents, and tells you what is
missing.
If pairing did not happen on its own
Section titled “If pairing did not happen on its own”Run zubriq-browse pair — the command prints a code like XXXX-XXXX
(valid once, for 10 minutes). In the browser: right-click the extension icon →
Options → advanced (or Pair with a code) → enter the code in
Pairing code → Connect. The command confirms which browser is paired.
zubriq-browse pair --list— paired browsers and when each was last seen;zubriq-browse pair --revoke <browser>— revoke a browser’s key and disconnect it.
Working with it
Section titled “Working with it”The agent works in its own tabs
Section titled “The agent works in its own tabs”- The agent opens tabs in the background of the window you used last and collects them into a collapsed group at the start of the tab strip. It cannot switch you to its tab or bring its window over your work.
- Pop-up windows opened by the agent’s page go into the same group.
- Tabs the agent has not touched for 10 minutes close on their own (configurable).
- A relay restart does not lose the agent’s tabs — the session takes them back.
While the extension is connected, Chrome shows a banner saying it “started debugging this browser” — that is expected. The Cancel button on it disconnects the extension from all tabs at once.
Give the agent one of your tabs
Section titled “Give the agent one of your tabs”Click the extension icon on the toolbar while on the tab you want — ON appears on the icon, and the tab is available to the agent. Click again — the tab is yours only again. The icon shows the state:
| Icon | Meaning |
|---|---|
| ON | the tab is given to the agent |
| RUN | the agent is working in it right now |
| WAIT | the agent is waiting for you (see below) |
| … | the relay is not running yet — the tab will go to the agent as soon as it starts working |
Clicking the icon always returns the tab to you and stops whatever the agent
was doing in it. The agent cannot close your tab. Browser service pages
(chrome://…, the extension store) cannot be given; for local files, enable
Allow access to file URLs on the extension’s card at
chrome://extensions.
When a human is needed: sign-in, code, payment
Section titled “When a human is needed: sign-in, code, payment”If a page has a sign-in, a two-factor code, a payment, or a “I’m not a robot” check, the agent does not solve it itself — it hands the tab to you. A small card with the site address appears on the page: do your part and press Continue on the card or click the extension icon. The agent continues from the same place. Only a real click can finish the handoff — the page cannot fake it.
Example requests
Section titled “Example requests”- “Open our dashboard at example.by and export the week’s order table to orders.csv” — the agent goes through the pages; if it asks you to sign in, sign in yourself and press Continue.
- “Check the signup form at localhost:3000: submit it empty and with a bad email, and tell me which errors are shown”.
- “Open the dashboard page and look at console errors on load”.
- “Take a screenshot of the payment page and save it to disk”.
- “Record a video of placing an order, from the cart to the confirmation”.
- “Compare prices for this item on three sites and put them in a table”.
What else the agent can do
Section titled “What else the agent can do”- Sessions — each has its own tabs and survives restarts
(
zubriq-browse session …). - Restrict sites — a session can be limited to the listed sites only: the agent will not follow a link, redirect, or pop-up to a foreign address. Ask the agent: “work only on example.by”.
- Network — recording the page’s requests; headers with keys, cookies,
and passwords are replaced with
[redacted]. - Screen recording — video of a tab in MP4 or WebM. The recording captures everything visible on the page, including your account data — check it before sending it to anyone.
- Several browsers — you can connect, for example, Chrome and Edge; new sessions open in the first connected one unless another is specified.
Settings
Section titled “Settings”Right-click the extension icon → Options. Changes take effect immediately.
- Where the agent opens tabs — in your window (default) or in a separate window beside it that does not take focus.
- Grouping — one shared group for all agents (default), a separate collapsed group per session, or no groups.
- Close tabs the agent has not touched — after 10 minutes (default), 30, 60, or never. Tabs where work is running, you are awaited, or a recording is on are not closed.
- Human-like input — on by default: smooth mouse movement and typing at a human pace. Off is faster, but sites detect bots more easily.
- Handoff notifications — only while the tab is being recorded (default) or on every handoff.
- Updates — install automatically (default), notify only, or never check.
The agent can also change these settings if you ask it to. Security and update settings are not available to the agent.
Security
Section titled “Security”The agent works in the browser where you are signed in to your accounts, so the extension assumes that a page or email read by the agent may try to drive it, and that other programs on the computer may try to connect to the relay.
- Only its own tabs. The agent sees and touches only the tabs it opened itself or that you gave it. The rest are unavailable to it.
- Relay is yours only. It listens only on
127.0.0.1; every request requires a token from a file only your user can read; requests from foreign sites are rejected. - A key per browser. A pairing code works once; five wrong codes in a row invalidate all pending ones. After that, the browser and relay prove to each other on every connection that they know the shared key.
- Debugger limits. The agent reads and writes cookies only on its own pages; clearing cookies, cache, and site data, closing the browser, granting sites permissions (camera, geolocation, etc.), and bringing the window to the front are forbidden.
- “I’m not a robot” checks are beyond the agent — it reports them and hands the tab to you.
- Fewer traces on disk. Session logs are visible only to you; passwords and codes entered there are replaced; they are kept for 14 days.
- Agent code runs in your name. Agent scripts run in a restricted environment (no access to files outside working folders and no network bypassing the browser), but it is not a sandbox: give the browser to an agent you trust.
What the model sees: pages the agent reads go to the model the agent works with — like any data in its session. The extension and relay send nothing anywhere else.
Extension permissions: debugger (drive tabs), tabs and tabGroups (its
own tabs and their group), scripting (the handoff card — only in the agent’s
tabs), webNavigation (the agent’s pop-ups — into its group), storage,
alarms, notifications (to tell you the agent is waiting) and access to all
sites — so the agent can work wherever you ask.
The browser on another computer
Section titled “The browser on another computer”If the agent runs on one computer (for example, a server) and the browser on another, run the relay next to the agent and connect the extension to it over the network:
- On the computer with the agent:
zubriq-browse set hostname 0.0.0.0. The command prints the address, port, and pairing code. - In the browser: the extension’s Options → advanced → enter that computer’s address and port in Relay address, enter the code → Connect.
The connection itself is not encrypted by the extension — use a secure network
(WireGuard, Tailscale), not the open internet. To return everything to one
computer: zubriq-browse set hostname 127.0.0.1.
Commands
Section titled “Commands”| Command | What it does |
|---|---|
zubriq-browse install |
pick agents, add the MCP server to them, install and pair the extension |
zubriq-browse status |
relay, extension, agent tabs, and what to fix (--json — for programs) |
zubriq-browse pair |
a code for manual pairing; --list, --revoke <browser> |
zubriq-browse update |
update now |
zubriq-browse relay restart |
restart the relay (after changing environment variables) |
zubriq-browse session … |
sessions: new, list, current, use, reset, delete; adopt — attach a tab you lent with the toolbar button to the session, allow — restrict sites |
zubriq-browse settings get / settings set … |
settings from the command line |
zubriq-browse extension |
extension folder for loading unpacked |
zubriq-browse uninstall |
remove the MCP server from agent configs |
zubriq-browse --help |
a short guide for the agent and all commands |
If something goes wrong
Section titled “If something goes wrong”- The agent does not see the browser.
zubriq-browse statuswill tell you what is missing: the extension is not installed, not paired, or outdated. After installing, restart the agent — MCP servers are picked up at start. - “The browser isn’t answering” on a heavily loaded computer — the browser
is just slow. Increase
OPENCODE_BROWSER_EXTENSION_TIMEOUT_MSandOPENCODE_BROWSER_PING_TIMEOUT_MSand runzubriq-browse relay restart. - The extension says it is not paired — run
zubriq-browse pairand enter the code (see above). - A page is “stuck” — check whether it has an
alert/confirmwindow: such windows block the tab; close it and tell the agent to continue. - The relay log:
~/.local/state/zubriq-browse/logs/relay.log.