Skip to content

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.

Three parts on your computer:

  1. The extension in the browser — runs commands in tabs through Chrome’s built-in debugger.
  2. Relay — a small local zubriq-browse process, listening only on 127.0.0.1. It starts on its own when the agent needs the browser.
  3. The zubriq-browse MCP 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.

  1. Install the zubriq-browse command:

    Окно терминала
    # macOS and Linux
    curl -fsSL https://zubriq.ai/browse.sh | sh
    Окно терминала
    # Windows (PowerShell)
    irm https://zubriq.ai/browse.ps1 | iex

    The installer puts zubriq-browse into ~/.local/bin and immediately runs zubriq-browse install.

  2. Pick the agents. The ones found on the computer are checked already: space to toggle, Enter to confirm. The installer adds the zubriq-browse MCP server to them. Running it again only adds — unchecking a box removes nothing.

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

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

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

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.

  • “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”.
  • 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.

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.

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.

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:

  1. On the computer with the agent: zubriq-browse set hostname 0.0.0.0. The command prints the address, port, and pairing code.
  2. 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.

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
  • The agent does not see the browser. zubriq-browse status will 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_MS and OPENCODE_BROWSER_PING_TIMEOUT_MS and run zubriq-browse relay restart.
  • The extension says it is not paired — run zubriq-browse pair and enter the code (see above).
  • A page is “stuck” — check whether it has an alert/confirm window: such windows block the tab; close it and tell the agent to continue.
  • The relay log: ~/.local/state/zubriq-browse/logs/relay.log.