Skip to main content
Glama
agent-browser

agent-browser

by NaifAlsultan
README.md
# agent-browser

An [MCP](https://modelcontextprotocol.io) server that gives AI agents a web browser running in the background,
built to be hard for sites to tell apart from a person's.

- **Invisible.** Google Chrome runs headed on its own virtual display (Xvfb), never on your screen.
- **Isolated.** Each agent session gets a fresh, temporary profile, deleted when the session ends.
- **Hard to detect.** Real Chrome driven through [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright),
  no automation flags, human-like mouse, keyboard and scroll input, and a realistic screen and GPU.
- **Honest about bot checks.** Self-clearing challenges are waited out; CAPTCHAs and block pages are reported to the
  agent, never solved.

Linux only.

> [!WARNING]
> agent-browser is not a security boundary. Agents browse by writing scripts that run with the server's
> permissions: files, environment variables, commands. The pages they read can prompt-inject them into writing harmful
> ones. Run the server in an OS-level sandbox (for example bubblewrap) that hides your files and environment, and
> don't rely on your MCP client's tool permissions to contain it.

## Detection results

| Page | Playwright (headless) | agent-browser |
| --- | --- | --- |
| [bot.sannysoft.com](https://bot.sannysoft.com) | 13 of 31 failed or warned | all passed |
| [BrowserScan](https://www.browserscan.net/bot-detection) | Robot | Normal |
| [CreepJS](https://abrahamjuliot.github.io/creepjs/) headless | 100% | 0% |
| [rebrowser bot detector](https://bot-detector.rebrowser.net/) | 6 red | all green |

Measured with Chrome 157 and a GPU (`scripts/detection-compare.ts`). Without a GPU, WebGL falls back to software
rendering, which some of these pages flag.

## How it works

```
MCP client ─stdio─▶ agent-browser ─▶ Patchright ─ws─▶ CDP proxy ═pipe═▶ Chrome ─▶ Xvfb
```

- One Chrome process per agent session, closed after 15 minutes idle.
- Chrome is launched directly, with DevTools over a pipe rather than an unauthenticated port.
- A small CDP proxy adds human-like input and removes Patchright's forced media emulation.
- The virtual display is protected by an X authority cookie.

## Tools

Like [browse](https://github.com/anomalyco/browse), one tool does the browsing: agents write Playwright code.

| Tool | What it does |
| --- | --- |
| `run({ code, timeoutMs? })` | Run Playwright JavaScript with `page`, `context` and `state` (kept between calls) in scope |
| `close()` | Close the session's browser and delete its profile |

The instructions tell agents to call `close()` when they're done browsing, so a session's Chrome doesn't hold memory
until the 15-minute idle timeout.

Helpers in `run`:

- `snapshot({ ref?, maxChars? })`: page outline with element refs such as `e12`, iframes included; password,
  one-time-code and card values hidden
- `ref(id)`: a locator for a ref from the latest snapshot
- `screenshot({ fullPage?, ref? })`: attach a screenshot to the result
- `log(...)` (or `console.log`): add a line to the result

```js
await page.goto("https://duckduckgo.com/?q=nixos")
return await snapshot()
```

Results include the return value, the page's title and URL afterwards, new tabs, dialogs (dismissed, except
leave-page prompts) and bot challenges. Each session's browser and scripts run in a worker thread: a script still
running at `timeoutMs` (60 s by default) is stopped by ending its worker, which closes that session's browser and
leaves other sessions alone.

Sessions are keyed by OpenCode's `ai.opencode/sessionID` request metadata, so each OpenCode session gets its own
browser. Clients that don't send it share one browser per server process, which for stdio clients is usually one per
client instance: parallel chats or subagents in it share tabs, cookies and `state`. If your client sends its own
per-conversation ID in `_meta`, set `AGENT_BROWSER_SESSION_META_KEY` to that key.

## Install

With Nix:

```nix
{
  inputs.agent-browser.url = "github:NaifAlsultan/agent-browser";
  # ...
  environment.systemPackages = [ inputs.agent-browser.packages.x86_64-linux.default ];
}
```

The package includes Chrome and Xvfb. Without Nix, you need Node.js 24+, Google Chrome and Xvfb:

```bash
npm ci --omit=dev
node src/main.ts
```

Then add it to your MCP client, for example OpenCode:

```json
{ "mcp": { "servers": { "agent-browser": { "type": "local", "command": ["agent-browser"] } } } }
```

## Configuration

| Variable | Default | |
| --- | --- | --- |
| `AGENT_BROWSER_CHROME` | `google-chrome-stable` | Chrome executable |
| `AGENT_BROWSER_XVFB` | `Xvfb` | Xvfb executable |
| `AGENT_BROWSER_SCREEN` | `1920x1080` | Screen size |
| `AGENT_BROWSER_GPU` | `auto` | `on`, `off` or `auto` (use `/dev/dri` when available) |
| `AGENT_BROWSER_IDLE_TIMEOUT_MS` | `900000` | Idle time before a session's browser closes |
| `AGENT_BROWSER_HUMAN_INPUT` | on | `off` for faster, more detectable input |
| `AGENT_BROWSER_CHROME_ARGS` | | Extra Chrome flags |
| `AGENT_BROWSER_TMPDIR` | system temp dir | Where profiles go |
| `AGENT_BROWSER_SESSION_META_KEY` | `ai.opencode/sessionID` | Request `_meta` key that identifies a session |
| `AGENT_BROWSER_DEBUG` | off | Verbose logs on stderr |

Also: `AGENT_BROWSER_ACTION_TIMEOUT_MS`, `AGENT_BROWSER_NAVIGATION_TIMEOUT_MS`, `AGENT_BROWSER_CHALLENGE_WAIT_MS`,
and optional `AGENT_BROWSER_XPROP` and `AGENT_BROWSER_SETPRIV` paths (set by the Nix package).

Notes:

- Chrome applies machine-wide policies from `/etc/opt/chrome/policies` to every profile, which can make the browser
  stand out.
- Chrome's sandbox needs unprivileged user namespaces. Where they're unavailable, pass `--no-sandbox` in
  `AGENT_BROWSER_CHROME_ARGS`.

## Development

```bash
nix develop
npm ci
npm test                    # unit tests
npm run test:integration    # real Chrome against local pages
npm run typecheck
```

## Credits

- [browse](https://github.com/anomalyco/browse) (MIT): human-like input, challenge detection and Patchright tuning,
  vendored in [`vendor/browse`](vendor/browse).
- [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) (Apache-2.0).

## License

MIT