Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

docs(agents): Cursor CLI beside the other five, why the folder it runs in has to be trusted, and what Windows does not get

Shahriarfbe559404028
diff --git a/README.md b/README.md
index 55d0d08..40547df 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
[![node](https://img.shields.io/node/v/browsentic)](https://nodejs.org)
[![license](https://img.shields.io/npm/l/browsentic)](LICENSE)
-Hand your real, logged-in browser to the AI agent you already run. Browsentic is a browser extension with an AI side panel, plus a small local daemon: open the panel beside any tab, say what you want and it drives the page, ask a question and it reads the page and answers. It runs on the agent CLI you already have logged in — five are supported — and doubles as an [MCP server](docs/guide/mcp-clients.md) so any MCP client can drive the same browser. No account, no API key, no cloud service.
+Hand your real, logged-in browser to the AI agent you already run. Browsentic is a browser extension with an AI side panel, plus a small local daemon: open the panel beside any tab, say what you want and it drives the page, ask a question and it reads the page and answers. It runs on the agent CLI you already have logged in — six are supported — and doubles as an [MCP server](docs/guide/mcp-clients.md) so any MCP client can drive the same browser. No account, no API key, no cloud service.
<p>
<strong>Works in</strong>&ensp;
@@ -24,7 +24,8 @@ Hand your real, logged-in browser to the AI agent you already run. Browsentic is
<picture><source media="(prefers-color-scheme: dark)" srcset="https://browsentic.com/icons/openai-dark.svg"><img src="https://browsentic.com/icons/openai.svg" width="18" height="18" alt=""></picture>&nbsp;<a href="https://developers.openai.com/codex/cli">Codex</a>&ensp;·&ensp;
<img src="https://browsentic.com/icons/antigravity.svg" width="18" height="18" alt="">&nbsp;<a href="https://antigravity.google/docs/cli/install">Antigravity</a>&ensp;·&ensp;
<img src="https://browsentic.com/icons/mistral.svg" width="18" height="18" alt="">&nbsp;<a href="https://github.com/mistralai/mistral-vibe">Mistral Vibe</a> <sup>beta</sup>&ensp;·&ensp;
- <picture><source media="(prefers-color-scheme: dark)" srcset="https://browsentic.com/icons/xai-dark.svg"><img src="https://browsentic.com/icons/xai.svg" width="18" height="18" alt=""></picture>&nbsp;<a href="https://docs.x.ai/build/overview">Grok Build</a> <sup>beta</sup>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="https://browsentic.com/icons/xai-dark.svg"><img src="https://browsentic.com/icons/xai.svg" width="18" height="18" alt=""></picture>&nbsp;<a href="https://docs.x.ai/build/overview">Grok Build</a> <sup>beta</sup>&ensp;·&ensp;
+ <picture><source media="(prefers-color-scheme: dark)" srcset="https://browsentic.com/icons/cursor-dark.svg"><img src="https://browsentic.com/icons/cursor.svg" width="18" height="18" alt=""></picture>&nbsp;<a href="https://cursor.com/docs/cli/overview">Cursor CLI</a> <sup>beta</sup>
</p>
## Quick Start
@@ -41,13 +42,13 @@ curl -fsSL https://browsentic.com/install.sh | sh
npx browsentic setup
```
-Either way two steps are left, both inside the browser: **Load unpacked** `~/browsentic/extension/chrome-mv3` at `chrome://extensions`, then paste the pairing code into the Browsentic popup. On Firefox, run `npx browsentic setup --browser firefox` instead: it links the signed `.xpi` from the [release](https://github.com/imshaikot/browsentic/releases/latest), and there is no folder to load. You also need one agent CLI logged in — `claude`, `codex`, `agy`, `vibe` (beta) or `grok` (beta). Windows and Linux follow the same two steps; the folder is under your home directory there too. Details, updating and building from source are in the [install guide](docs/guide/install.md).
+Either way two steps are left, both inside the browser: **Load unpacked** `~/browsentic/extension/chrome-mv3` at `chrome://extensions`, then paste the pairing code into the Browsentic popup. On Firefox, run `npx browsentic setup --browser firefox` instead: it links the signed `.xpi` from the [release](https://github.com/imshaikot/browsentic/releases/latest), and there is no folder to load. You also need one agent CLI logged in — `claude`, `codex`, `agy`, `vibe` (beta), `grok` (beta) or `cursor-agent` (beta). Windows and Linux follow the same two steps; the folder is under your home directory there too. Details, updating and building from source are in the [install guide](docs/guide/install.md).
## Key Capabilities
- **A Side Panel, Not a Terminal**: Open it beside any tab, type or dictate, and watch every action land on a timeline with approvals where you are looking. The terminal is optional: the same daemon doubles as an MCP server for Claude Code, Cursor or Zed
- **Your Real Browser, Not a Headless One**: Drives the tab in front of you, in your own profile, with your own logins and sessions
-- **Bring Your Own Agent**: Runs on the agent CLI you already have and are already signed in to — switch between Claude Code, Codex, Antigravity, Mistral Vibe and Grok Build with one click, and pick the model each one runs
+- **Bring Your Own Agent**: Runs on the agent CLI you already have and are already signed in to — switch between Claude Code, Codex, Antigravity, Mistral Vibe, Grok Build and Cursor CLI with one click, and pick the model each one runs
- **52 Page Capabilities**: Reading, clicking, typing, dragging, on-site search, form submission, navigation, stepping into iframes, screenshots, file upload and download, captchas, theming and accessibility, console and network diagnostics, background progress monitoring, scheduled and repeating jobs, pointing at an element, and calling the tools a WebMCP site registers for agents
- **Live Tools, Off By Default**: For work that repeats twenty times or needs something no tool covers, flip the **Live tool** switch and the agent may write a small script for the page — you read the code in the panel and approve it before a line of it runs
- **Keep What It Wrote**: A script that worked can be kept as a tool of your own, named after the site it belongs to (`youtube.com:watch:darken-page-except-video-player`) and run later by typing `/`. The code stays in the browser; no MCP client can reach it
diff --git a/docs/guide/agents.md b/docs/guide/agents.md
index 37f3ac4..bf4bfdf 100644
--- a/docs/guide/agents.md
+++ b/docs/guide/agents.md
@@ -1,7 +1,7 @@
# Choosing an agent
-The side panel runs on an agent CLI you already have logged in. Five are supported — Mistral Vibe
-and Grok Build in beta — and switching is a click.
+The side panel runs on an agent CLI you already have logged in. Six are supported — Mistral Vibe,
+Grok Build and Cursor CLI in beta — and switching is a click.
This is only about the **side panel**. Driving Browsentic *from* another tool is
[MCP clients](mcp-clients.md), and that direction is fully agent-agnostic.
@@ -32,18 +32,18 @@ agents cannot resume each other's sessions, so the next instruction starts a fre
---
-## The five
+## The six
-| | Claude Code | Codex | Antigravity | Mistral Vibe (beta) | Grok Build (beta) |
-| --- | --- | --- | --- | --- | --- |
-| Vendor | Anthropic | OpenAI | Google | Mistral AI | xAI |
-| Binary | `claude` | `codex` | `agy` | `vibe` | `grok` |
-| Install | `npm i -g @anthropic-ai/claude-code` | `npm i -g @openai/codex` | [antigravity.google/docs/cli/install](https://antigravity.google/docs/cli/install) | `uv tool install mistral-vibe` | `curl -fsSL https://x.ai/cli/install.sh \| bash` |
-| Default model | `claude-sonnet-5` | the CLI's own | the CLI's own | the CLI's own | the CLI's own |
-| Effort names | `low`…`max` | `low`…`xhigh` | `low`…`high` | none — set `thinking` in Vibe's own config | `low`…`xhigh` |
-| Kept off your machine by | a per-run tool allowlist plus an explicit deny list | a read-only sandbox (`sandbox_mode="read-only"`) | its own permission rules | a per-run tool allowlist — its shell and file tools are never loaded | a per-run tool list, approvals that refuse anything not granted up front, and a kernel sandbox that keeps its writes in its own folder |
+| | Claude Code | Codex | Antigravity | Mistral Vibe (beta) | Grok Build (beta) | Cursor CLI (beta) |
+| --- | --- | --- | --- | --- | --- | --- |
+| Vendor | Anthropic | OpenAI | Google | Mistral AI | xAI | Anysphere |
+| Binary | `claude` | `codex` | `agy` | `vibe` | `grok` | `cursor-agent` |
+| Install | `npm i -g @anthropic-ai/claude-code` | `npm i -g @openai/codex` | [antigravity.google/docs/cli/install](https://antigravity.google/docs/cli/install) | `uv tool install mistral-vibe` | `curl -fsSL https://x.ai/cli/install.sh \| bash` | `curl https://cursor.com/install -fsS \| bash` |
+| Default model | `claude-sonnet-5` | the CLI's own | the CLI's own | the CLI's own | the CLI's own | the CLI's own |
+| Effort names | `low`…`max` | `low`…`xhigh` | `low`…`high` | none — set `thinking` in Vibe's own config | `low`…`xhigh` | none — put it in the model id, e.g. `claude-opus-4-8[effort=high]` |
+| Kept off your machine by | a per-run tool allowlist plus an explicit deny list | a read-only sandbox (`sandbox_mode="read-only"`) | its own permission rules | a per-run tool allowlist — its shell and file tools are never loaded | a per-run tool list, approvals that refuse anything not granted up front, and a kernel sandbox that keeps its writes in its own folder | per-run deny rules, where a deny beats every allow; a kernel sandbox is asked for too but not depended on |
-All five get the same system prompt, the same `browsentic` MCP server pointed back at the daemon,
+All six get the same system prompt, the same `browsentic` MCP server pointed back at the daemon,
and the same [approval gate](approvals.md). What differs is how well each one can be fenced off from
the rest of your machine — see [internals/guardrails.md § Spawn containment](../internals/guardrails.md#spawn-containment)
for exactly what each flag buys.
@@ -112,6 +112,30 @@ rate-limited before the model answered. Expect rough edges, and please report th
---
+### Cursor CLI is in beta
+
+Browsentic's Cursor runner was checked against `cursor-agent 2026.09.18-9a7762b`: every flag it
+passes is accepted, a real turn was read back from its stream, and the deny rules were measured
+refusing a shell command in a headless run. What has not been through it yet is a whole
+conversation in the side panel — the browser tools reaching a page, and a follow-up turn resuming.
+Expect rough edges there, and please report them.
+
+- **Sign in first.** Run `cursor-agent login`, or set `CURSOR_API_KEY`. Until then a run fails with
+ *Authentication required*.
+- **Your own Cursor MCP servers are denied by name.** A project config does not replace the global
+ `~/.cursor/mcp.json`, so every server you configured for Cursor itself would otherwise load
+ beside Browsentic's — including your own `browsentic` entry, which reaches the browser without a
+ run's approval gate. Browsentic reads that file and denies each of them for the run. It never
+ writes to it.
+- **Reasoning effort goes in the model id.** Cursor has no effort flag; it takes bracket overrides
+ instead, so set `agents.cursor.model` to something like `claude-opus-4-8[effort=high]`.
+- **On Windows, only the deny rules apply.** Cursor's kernel sandbox is macOS and Linux only.
+- **Each conversation leaves an entry in `~/.cursor/projects`.** Cursor records a project per
+ directory it is run in, and Browsentic gives each conversation its own. They are swept with the
+ conversation's workspace after a day.
+
+---
+
## Per-agent settings
In `~/.browsentic/config.json`:
@@ -124,7 +148,8 @@ In `~/.browsentic/config.json`:
"codex": { "bin": "codex", "model": "gpt-5.6-terra" },
"antigravity": { "bin": "agy" },
"vibe": { "bin": "vibe" },
- "grok": { "bin": "grok", "model": "grok-4.7" }
+ "grok": { "bin": "grok", "model": "grok-4.7" },
+ "cursor": { "bin": "cursor-agent", "model": "composer-2.5" }
}
}
```
@@ -155,6 +180,8 @@ Claude runner's settings.
| "does not understand the flags Browsentic uses" | The CLI is too old. Update it. |
| Antigravity answers but never touches the page | Its permission rule was removed. `browsentic agent` reports *needs setup* again. |
| Grok Build sits silent for minutes, then *xAI did not answer* | The Grok account is rate-limited — a free one usually is. Wait, or upgrade the account. |
+| Cursor CLI: *Authentication required* | The daemon inherits no session. Run `cursor-agent login`, or set `CURSOR_API_KEY`, then retry. |
+| Cursor CLI on Windows | Cursor's sandbox has no Windows backend, so only the deny rules apply there. The browser still works; the machine is less fenced off than on macOS or Linux. |
| `AGENT_UNSAFE`: *Grok Build offered this run …* | Grok offered tools Browsentic never asks for, so the run was stopped before the model saw them. Update Grok Build and Browsentic, and report it if it persists. |
---
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index 0ed82d1..fbb5f9d 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -49,7 +49,7 @@ Nothing here is required; this shows every key in one place.
| Key | Default | Notes |
| --- | --- | --- |
-| `agent` | `claude` | Which CLI the side panel runs on: `claude`, `codex`, `antigravity`, `vibe` or `grok` |
+| `agent` | `claude` | Which CLI the side panel runs on: `claude`, `codex`, `antigravity`, `vibe`, `grok` or `cursor` |
| `agents.<name>.bin` | the CLI's own command name | Absolute path to the binary |
| `agents.<name>.model` | `claude-sonnet-5` for Claude, else the CLI's default | Passed as `--model`; the agent picker's model select writes it |
| `agents.<name>.effort` | unset | That CLI's reasoning-effort flag; an unaccepted value is dropped |
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index 4c103c9..2784ca5 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -61,6 +61,9 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d
| Codex sees only part of a long page | Codex cuts a tool result over 25,000 tokens; an older Browsentic left its 10,000 default in place | Update Browsentic, then ask for less at a time: a smaller `maxPerKind`, or `page_extractText` group by group |
| Mistral Vibe: every action on a follow-up turn fails with `RUN_INACTIVE` | Vibe re-reads a resumed session from the folder it began in, and an older Browsentic wrote each turn to a folder of its own | Update Browsentic, then start a new conversation: one begun before the update keeps its first folder |
| Grok Build sits silent for minutes, then fails with *xAI did not answer* | The Grok account is rate-limited, as a free one is; Grok retries quietly before giving up | Wait, or upgrade the account |
+| Cursor CLI fails with *Authentication required* | The daemon inherits no session | `cursor-agent login`, or set `CURSOR_API_KEY` |
+| Cursor CLI reaches an MCP server you did not expect | A project `.cursor/mcp.json` does not replace your global one, so every server you gave Cursor loads too | Browsentic denies each by name for the run; if one still answers, update Browsentic and report it |
+| Cursor CLI is less fenced off on Windows | Cursor's kernel sandbox has no Windows backend | Nothing to do — the deny rules still apply; treat a Windows run as `host`-class |
| `AGENT_UNSAFE`: *Grok Build offered this run …* | Grok offered tools Browsentic never asks for, so the run was stopped before the model saw them | Update Grok Build and Browsentic; report it if it persists |
## Pages and tabs
diff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.md
index 0d0913a..ccfe1bc 100644
--- a/docs/internals/guardrails.md
+++ b/docs/internals/guardrails.md
@@ -345,6 +345,7 @@ type LocalTools = 'allowlist' | 'sandbox' | 'host'
| **Antigravity** | `host` | No tool list and no sandbox flag; its built-in tools are governed by the user's own CLI settings, so a sealed environment is the only containment Browsentic applies |
| **Mistral Vibe** | `allowlist` | `--enabled-tools` is the whole of what loads: Browsentic's MCP tools, plus web search and fetch on a research run. The shell and file tools never exist in the run, and `--auto-approve` is a forbidden flag |
| **Grok Build** | `allowlist` | A per-run built-in tool list, `--permission-mode dontAsk`, deny rules, and a kernel sandbox for writes. Reads are closed by the tool list and a `Read` deny rather than the sandbox, and MCP servers the user set up in Grok itself still load |
+| **Cursor CLI** | `allowlist` | Deny rules in a project `.cursor/cli.json`, where **a deny beats every allow** — including the user's own. Measured against 2026.09.18: a headless run asked to `echo` a marker got `permissionDenied`, twice, and gave up. `--sandbox enabled` is asked for as well but not depended on, and it has no Windows backend. This is the first runner whose containment lives in a file rather than in argv, which is why `vetPlan` checks file *content* and not only that the file was written. `--trust` is **required**, not forbidden: headless Cursor refuses to start in a folder nobody trusted, and the folder is one Browsentic created and wrote every file in — it grants no tool permission of its own |
#### Grok Build, and why not always-approve
@@ -418,6 +419,7 @@ Each agent keeps only the prefixes it needs to authenticate:
| Antigravity | `GEMINI_`, `GOOGLE_`, `ANTIGRAVITY_` |
| Mistral Vibe | `MISTRAL_`, `VIBE_` |
| Grok Build | `XAI_`, `GROK_` |
+| Cursor CLI | `CURSOR_` |
Plus **federated** cases, where a flag turns another prefix into the agent's own credentials: Claude
Code on Bedrock authenticates with `AWS_*`, so sealing it would be sealing the agent out of its own