Use your Chrome

Haarness agents can work in your own Google Chrome, with the accounts you are signed in to, through the Haarness for Chrome extension. Use it for tasks that need your sign-in, such as "download last month's invoice from my billing page". It works from Desktop, the terminal UI, haarness run and the SDKs, so you do not need Desktop open to browse.

For a dev server, or a site that needs no sign-in, Desktop's built-in browser keeps each chat in its own private profile instead.

You need: Google Chrome 125 or later on the computer that runs your Haarness projects. Haarness for Chrome comes with Haarness: the haarness command from the install command and the Desktop app both include it. It is not in the Chrome Web Store yet, so you load it into Chrome yourself, once.

Before you start, know what you are allowing:

• Every site asks first, in each chat. Auto, --yolo and your permission rules do not answer for you.
• Agents use only their own tab groups. Your other tabs are left alone.
• You can pause or stop Haarness from its button in Chrome's toolbar at any time.

Set up Chrome from Desktop

1. Open Settings → Browser and go to the Chrome group. Click Set up Chrome….
2. Use Chrome with Haarness opens and prepares Chrome to start Haarness. It shows Chrome can start Haarness when that is done.
3. Under Add Haarness for Chrome, follow the steps it shows:
   1. Copy the address chrome://extensions and open it in Chrome. Desktop cannot open it for you.
   2. Turn on Developer mode at the top right of that page, and keep it on.
   3. Click Load unpacked. In the folder picker, press ⌘⇧G on macOS (Ctrl+L on Windows and Linux) and paste the folder path Desktop shows; the copy button next to it copies it. You can also click Reveal in Finder (Show in Explorer on Windows, Show in file manager on Linux) and drag the folder onto the picker.
   4. Pin Haarness to the toolbar: click the puzzle-piece button in Chrome's toolbar, then the pin next to Haarness.
4. Desktop shows Waiting for Chrome… and then Connected to Google Chrome.

Try it: ask "open example.com in Chrome and summarise it". The Chrome row in Settings → Browser now reads Connected · Google Chrome.

Set up Chrome from the terminal UI

Type /chrome (or /browser). The panel shows whether Chrome is connected and what to do next; /chrome setup starts the setup at once.

1. Press Enter to set up. Haarness prepares Chrome and shows the steps above, with the folder path to paste after Load unpacked. Press c to copy it.
2. Follow the steps in Chrome: Developer mode, Load unpacked, then pin Haarness to the toolbar.
3. The panel says Chrome is connected. Press Esc to close it.

While it is open, e turns Let agents use Chrome on or off and d changes Browser for new agent tabs. /status also has a Chrome line.

Set up Chrome from the command line

haarness browser setup

It prepares Chrome to start Haarness and ends with the next step, such as "Next, add Haarness for Chrome: open chrome://extensions, turn on Developer mode (keep it on), click Load unpacked, press ⌘⇧G and paste:", then the folder path and "Then pin Haarness to the toolbar." On Linux it says Ctrl+L; on Windows, paste the path into the folder box.

After remove, Desktop no longer sets Chrome up again by itself. Remove Haarness from chrome://extensions as well.

Setup also prepares Chrome Beta, Chrome Canary, Chromium, Microsoft Edge, Brave and Vivaldi (not on Windows), and Chrome for Testing on macOS, when it finds them. --browser picks one or more: chrome, chrome-beta, chrome-canary, chrome-for-testing, chromium, edge, brave or vivaldi. To use one of them, load Haarness for Chrome the same way from that browser's own extensions page, such as edge://extensions. Haarness then shows it by its own name, such as Connected · Microsoft Edge.

If HAARNESS_HOME or HAARNESS_DATA_DIR is set, or you pass --data-dir, setup stops and says why; see Chrome does not connect.

Download Haarness for Chrome

The download page offers Haarness for Chrome as a zip, with its SHA-256 checksum. You do not need it to get started: the haarness command and Desktop already include it, and the setup above prepares the folder to load. Download it to keep the released files yourself:

1. Download the zip and unzip it.
2. Run haarness browser setup on the same computer. Chrome needs it to start Haarness, whichever folder you load.
3. Open chrome://extensions, turn on Developer mode, click Load unpacked and choose the unzipped folder. Pin Haarness to the toolbar.

The direct link to the latest one is https://haarness.ai/api/v1/releases/stable/chrome-extension/download (preview instead of stable for the preview channel).

Install it for your team

An administrator can install Haarness for Chrome on the Chrome browsers their organization manages, without Developer mode, through Chrome's ExtensionInstallForcelist policy. Add this entry:

accdjhmcgljbadpeanajllmcembhkomn;https://haarness.ai/api/v1/releases/stable/chrome-extension/updates.xml

Chrome then installs the signed package of the current stable release and updates it with every release (preview instead of stable follows the preview channel). Chrome accepts an extension from outside the Chrome Web Store only on browsers your organization manages.

Each person still runs haarness browser setup once, or opens Desktop, which does it for them, so that Chrome can start Haarness on their computer.

Keep it up to date

• Set up with Desktop: each time Desktop starts after an update, it refreshes the folder setup prepared, and Haarness for Chrome reloads itself when no agent is using it.
• Set up with the terminal UI or haarness browser setup: after you update Haarness, run haarness browser setup again (or /chrome setup) to refresh the folder. Until you do, the Haarness button in Chrome's toolbar may say Update needed, with the command to copy.
• Loaded from a zip: Chrome keeps running the folder you chose. When Haarness is newer, the Haarness button shows Update ready: load the newer zip, or the folder setup prints, in its place.
• Installed for your team: Chrome updates it from the policy's address.

What can agents do in Chrome?

The same things as in Desktop's browser: open tabs, read pages, click, type, fill in forms, take screenshots, upload files from your project and fetch downloads. Lighthouse audits, performance traces and CPU or memory profiling work only in Desktop's built-in browser.

• Only in their own tab groups. Each chat gets a tab group named after the chat, and a helper agent gets its own, with at most 32 tabs per chat. A new tab opens in the background of the window you used last, and Haarness never brings Chrome to the front by itself. In the window you are working in, agent tabs stay behind yours; if the agent needs a screenshot of one, it may ask you to show that tab.
• Your network. Pages load over your own connection, VPN and proxy, and localhost is your computer.
• Share a tab by dragging it into a chat's group. Take it back by dragging it out, ungrouping it or closing it; the agent is told you took it back. A page that an agent's tab opens in a new tab joins its group; a pop-up in a window of its own usually does not, and the agent cannot use it.
• Never: chrome:// pages, other extensions, files on your computer (file://), DevTools, or Incognito windows.
• File pickers: a file chooser that a page opens during an agent's action, or in the 5 seconds after it, does not appear; the agent uploads files its own way instead.
• Your site settings stay: a site you already allowed to use the camera, microphone, location or notifications keeps that permission while an agent drives it.
• Which browser a new tab uses is set by Browser for new agent tabs, in Settings → Browser or with d in /chrome. Automatic, the default, uses the Haarness browser when the chat is open in Desktop, otherwise Chrome. You can also just say "in Chrome" in your message.
• Scheduled runs do not pick Chrome under Automatic, and neither do the helper agents and workflows they start. A scheduled run that does use Chrome cannot ask you, so it can use only sites you set to Always allow (see below).

Downloads

A file an agent downloads is saved where Chrome saves your downloads, and stays there. The agent gets a copy of up to 5 MiB in your project's .haarness-chat-attachments folder, which Haarness keeps out of Git. Only a download that starts in the agent's tab, while it acts or within 10 seconds after (an Export button that prepares the file first, say), counts as the agent's; the agent never sees your other downloads.

If Ask where to save each file before downloading is on in Chrome's download settings, Chrome opens its Save dialog, which the agent cannot answer, so the download does not finish until you do. Turn that setting off at chrome://settings/downloads if agents should download without you.

The bar at the top of Chrome

While an agent is working, Chrome shows a bar at the top saying that "Haarness" started debugging this browser, because that is how the extension controls tabs. It goes away about 30 seconds after the agent's last action. Cancel on that bar stops Haarness in this browser; see Stop or pause it.

Chat titles in tab groups

Tab groups are named after your chats. If Chrome syncs your tab groups to your Google account, those chat titles are synced too.

Approve a site in Chrome

Out of the box, browsing, downloads, uploads and scripts all ask first, for every site. The request says Allow in Chrome and what the agent wants, such as Use https://example.com in Chrome, followed by what that action uses: the address, the script it runs, the text it types or the files it uploads.

Desktop shows the three as buttons; the keys are the terminal UI's.

You can answer from the Haarness button in Chrome too: a waiting request shows Waiting for you with Allow in this chat and Deny, and the button shows !. A request that also needs an answer outside Chrome, such as an upload of a file outside the project, says to answer it in Haarness. haarness run at a terminal asks y (allow in this chat), o (once) or N.

• Each kind of action asks on its own. A site you allowed for browsing still asks before the agent downloads from it, uploads to it, or runs a script on it (Run scripts on … in Chrome). A script can read anything on the page, so allow it only where you would.
• Other chats ask again. An answer never carries over to another chat, and ends when the Haarness server for that project stops.
• Auto does not answer these. In Chrome the agent acts as you, in accounts where a mistake can send a message, pay or delete. So Auto, --yolo, hooks and allow rules in your configuration never approve a Chrome site. A chat you share with /rc cannot answer from your phone either: answer on the computer running Chrome, or through Remote control › Hosts, which opens that computer itself. In a schedule the agent's Chrome action fails at once and the agent is told which site needs you; haarness run with no terminal stops and names the site.

Stop being asked about a site

In Settings → Browser → Chrome site permissions, add the site and set Browsing, Downloads, Uploads and Scripts to Always allow, Requires approval or Block. The Default row covers every other site.

• These settings apply to every project on this computer. A project's own settings can only make Chrome stricter, never looser.
• A site you Block under Agent site permissions, for Desktop's browser, is blocked in Chrome too. Always allow there does not carry over.
• Let agents use Chrome turns Chrome off for agents. Turning Agent browser control off also turns Chrome off, and so can a project's own settings. Settings → Browser and /chrome say which one keeps Chrome off.
• While an agent works, Chrome does not load pages, frames or images from a site you Block, even inside a page you allowed; the rest of the page still works. Requests a page makes from its workers, and WebSocket connections, are not filtered this way.

Stop or pause it

Click the Haarness button in Chrome's toolbar. It lists the chats using this Chrome:

• Stop next to a working chat stops that chat's turn, as stopping it in Haarness would.
• Show tabs brings that chat's tab group to the front; Close tabs closes them, and Close all agent tabs closes every chat's tabs.
• Turn off Let Haarness use this browser to pause. Work in progress stops at once and agents are told you paused Haarness, until you turn it back on.
• Cancel on the debugging bar stops everything Haarness is doing in this Chrome. Agents cannot use Chrome again until you click Resume on the Haarness button.
• Alt+Shift+S, Stop Haarness in this browser, stops every chat working in this Chrome and, like Cancel, keeps agents out until you click Resume on the Haarness button. The button shows the keys next to Stop all; change them at chrome://extensions/shortcuts.

Pages you click or type in yourself are yours: what you do in a tab is not an agent action.

Use more than one Chrome profile

Load Haarness for Chrome in each Chrome profile you want agents to use. A chat keeps using the profile that already has its tabs; a new chat uses the profile you used last. To tell profiles apart, give each a Profile label on the Haarness for Chrome welcome page, opened with Settings & help on the Haarness button.

Chrome does not connect

• The Haarness button says Not set up. Chrome cannot start Haarness. Run the setup again (Set up Chrome…, /chrome or haarness browser setup), then reopen the button. Do the same after you move Haarness Desktop: on a Mac it must be in your Applications folder, not run from the disk image.
• Developer mode was turned off. Turn it back on at chrome://extensions.
• Chrome is connected, but the agent says it is not. Click Settings & help on the Haarness button. Under Connected projects, a project Chrome cannot use shows Error and why:
  • "Restart this project's Haarness server.": the server refused Chrome, most often because it is older than Haarness for Chrome. When its running work has finished, run haarness serve --stop in that project and open the project again.
  • "This project's Haarness server does not accept Chrome. Restart it without --anonymous.": you started it yourself with haarness serve and no token, or with --anonymous. Start it again with HAARNESS_SERVER_TOKEN set.
• You use HAARNESS_HOME, HAARNESS_DATA_DIR or --data-dir. Chrome reaches the projects of your usual Haarness data folder. With one of these set, haarness browser setup stops and explains why: your Chrome would start Haarness from that folder, and stop working once you delete it. To use it anyway, run haarness browser setup --use-isolated-data-for-chrome with the same setting; Chrome then reaches that folder's projects too, until you run haarness browser setup without it.
• A work or school Chrome. Your organization may block extensions you load yourself, or the way Chrome starts Haarness. chrome://policy lists the rules it sets; ask your administrator.
• Chrome from Flatpak or Snap (Linux) cannot start Haarness. Install Chrome from Google's package instead. haarness browser status says which browsers it could not set up.

What does not work yet

• Projects on another computer: Chrome works with Haarness projects on the computer where Chrome runs. A project on a remote server, in Desktop or through haarness attach, cannot use it.
• Firefox and Safari are not supported.
• The Chrome Web Store: Haarness for Chrome is not listed there yet. Load it unpacked, or have your organization install it by policy.

Next

• Websites in your Chrome: how its approvals fit with the rest of Haarness's permissions
• What can an agent do in my Chrome?: what you trust when you allow a site