Source: https://harnsy.dev/docs/browser

> A browser on your machine for your AI agents: they open pages, click and fill in forms; you watch a live screen and step in at any time. Every edition.

# The agents&#39; browser

harnsy can run a browser on your machine for your agents. An agent opens a page, reads it, clicks and fills a form; you watch the same browser on a live screen in the dashboard and can step in at any moment. It runs on your machine, with your sign-ins, and nothing goes through us. In every edition.

**What you need.**

- Linux or macOS.
- Node.js 20 or newer on the machine.
- About 189 MB to download and about 420 MB on disk. Everything goes into `~/.harnsy/browser/`: nothing is installed into the system and no administrator rights are needed.

If Google Chrome is installed, the browser runs it; otherwise it runs harnsy's own Chromium. The browser speaks English whatever the machine's language.

## 1. Install it

Open the dashboard on this machine: Settings › Browsers › «Install». The section shows the two steps and their percent. If a step fails, it says why; «Details» shows more and «Try again» repeats it. harnsy is built to let only you install it, from this machine's own dashboard: not an agent, not a phone signed in from outside.

When it is done, harnsy makes the first profile, «Main».

**Ubuntu 23.10 and newer, or a server.** The browser may not start at first. The section then shows one command to run once in a terminal of this machine (or install Google Chrome). The section shows a warning if the browser runs without its protection: do not leave it that way.

## 2. Profiles

A profile is one separate browser memory: its sign-ins, cookies and site data. Make one per purpose or account: «Work», «Shop». By design an agent given «Work» is not handed «Shop».

- «+ Profile», a name, «Add».
- A profile sleeps when nobody used it for 15 minutes and wakes by itself on the next action. «⋯» › «Put to sleep» closes it now, after saving its sign-ins.
- «Remove» asks first: all sign-ins saved in that profile are erased.

## 3. Give a profile to a role

An agent gets no browser until you allow it. On the profile's page, under «Given to», press «Change» and pick projects and roles. Give it only to roles whose work needs websites. Those agents then have the browser's tools (open, click, type, read), and harnsy hands them no password or cookie of yours.

They use the tools without asking you each time. To be asked per action, set that on the profile's connection in Settings › Services for agents › MCP.

## 4. Sign in to a site yourself

1. Open the browser's screen (step 5) and go to the site's login page.
2. Type the login and password yourself, with the code if it asks.
3. The profile keeps the sign-in, and the agent works in that account.

The agent does not need your password: do not give it one, and do not paste passwords into messages to agents.

The profile's page lists the sites it is signed in to, with dates only (a cookie's value is never shown). «⋯» › «Sign out of the site» is built to erase that site's data in the profile and sign the agents out there.

## 5. Watch, step in, talk

When a project has a profile, a monitor icon appears in the project's header; a dot on it means a tab is waiting for you. Press it to open «Agents' browser»: the profiles and their tabs on the left, the page on the right.

- **Click the page** to use it: your mouse and keyboard go to the browser.
- **«Take control»** makes a tab yours: harnsy is built to keep the agent from clicking and typing there until you press «Hand back to the agent». A tab comes back by itself a minute after you close the screen, or after 15 minutes without a key or click.
- **When an agent needs you** in a tab (a sign-in, a robot check), the bar above the page says so. Do it, then press «I'm in — hand back to the agent».
- **«Chat»** opens a chat with the agent working in that tab, next to the page. Your message carries the tab's title and address. «Snapshot» attaches a picture of the page, «Area» a part of it.

harnsy does not record the screen; only a snapshot you attach to a chat is kept, with that message.

## What it cannot reach

The browser opens public websites only. It is built to refuse this machine's own addresses (`localhost`), your router, printers and other computers on your network.

## Memory, backups

A running profile takes up to 2 GiB of memory; Resources › «This node's browser» shows what each profile and tab uses, where you can put one to sleep or close a tab. Sign-ins are part of the machine's [backups](https://harnsy.dev/docs/backups) and of a move; a profile with more than 50 MB of saved data is left out and marked «too big for a backup»: sign in there again after a restore.

## Risks, plainly

- **Sites may notice automation.** Some ask for a robot check or block the visit. You can solve the check yourself on the screen.
- **Sites have their own rules.** Some forbid automated use of an account and may lock it. Where a site's terms forbid it, leave that site out. You answer for following the terms of the sites you give to agents.
- **An agent can act in every account of its profile.** Keep important sign-ins out of a profile you give to many roles.
- **Pages are not trusted.** A page can hold text aimed at the agent. harnsy marks what comes from a page as outside data, not a command. An agent can still be misled by it: give the browser only to roles whose work needs it, and watch them on sites that matter.

## If something goes wrong

| You see | Usually |
| --- | --- |
| «Install» says Node.js is needed | install Node.js 20 or newer, then press «Install» again |
| the browser does not start (Ubuntu, a server) | run the command the section shows, once |
| «The browser stopped: …» | it starts again on the agent's next action; the reason is in the line |
| «Connection closed» on the screen | press «Reconnect» |
| a site answered 403 or a robot check | open the page on the screen and look; see «Risks» |

[What it does →](https://harnsy.dev/features/browser)

[Questions? Ask on Discord →](https://discord.gg/nBrMhZPWzv)

Anthropic, Claude Code, OpenAI, ChatGPT, Codex, OpenCode, pi, Telegram, Discord, GitHub, Apple, macOS, iOS, iPhone, Safari, Google, Android, Chrome, Microsoft, Windows, Windows Security, Defender and QR Code are names of their owners’ products. harnsy is not affiliated with or endorsed by them. iOS is a trademark of Cisco used under licence by Apple; QR Code is a registered trademark of DENSO WAVE INCORPORATED. No logos.
