> ## Documentation index
> Fetch the complete documentation index at: https://haarness.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://haarness.ai/docs/desktop/previews-and-browser.md#browse-next-to-the-chat) 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](https://haarness.ai/docs/start/install.md) 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

```sh
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.

| To | Run |
| --- | --- |
| See whether Chrome is set up and which projects it reaches | `haarness browser status` |
| Undo the setup | `haarness browser remove` |
| Also delete the extension folder | `haarness browser remove --all` |

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](https://haarness.ai/docs/desktop/use-your-chrome.md#chrome-does-not-connect).

## Download Haarness for Chrome

The [download page](https://haarness.ai/download) 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:

```text
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](https://haarness.ai/docs/desktop/use-your-chrome.md#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.

| Answer | Key | Allows |
| --- | --- | --- |
| **Allow in this chat** | `a` | That site, for that kind of action, in this chat until the Haarness server stops |
| **Allow once** | `y` | This one action |
| **Deny** | `n` | Nothing. The agent is told you said no |

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`](https://haarness.ai/docs/cloud/remote-hosts.md#continue-a-chat-on-your-phone) cannot answer from your phone
  either: answer on the computer running Chrome, or through
  [Remote control › Hosts](https://haarness.ai/docs/cloud/remote-hosts.md#connect-your-computer), which opens that
  computer itself. In a [schedule](https://haarness.ai/docs/cli/schedules.md) 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](https://haarness.ai/docs/security/permissions.md#websites-in-your-chrome): how its approvals
  fit with the rest of Haarness's permissions
- [What can an agent do in my Chrome?](https://haarness.ai/docs/security/trust-boundaries.md#what-can-an-agent-do-in-my-chrome):
  what you trust when you allow a site