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): Grok Build beside the other three, what keeps it contained, and what a rate-limited account does to a run

Shahriardcde7404857c
diff --git a/README.md b/README.md
index f49fbec..944ad8f 100644
--- a/README.md
+++ b/README.md
@@ -24,13 +24,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` or `agy`. 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` or `grok` (beta). 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 pay for and are already signed in to — switch between Claude Code, Codex, Antigravity and Mistral Vibe 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 and Grok Build 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/README.md b/docs/README.md
index 4360dce..616a43a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -19,7 +19,7 @@ Start here if you want to run Browsentic on your own machine.
| [Pair](guide/pair.md) | Connect your browser with a single-use code |
| [First run](guide/first-run.md) | A tour of the side panel and your first instruction |
| [Features](guide/features/) | One page per capability — what it does and when to reach for it |
-| [Choosing an agent](guide/agents.md) | Claude Code, Codex or Antigravity |
+| [Choosing an agent](guide/agents.md) | Claude Code, Codex, Antigravity or Grok Build |
| [MCP clients](guide/mcp-clients.md) | Optional: drive the same browser from Claude Code, Cursor, Zed or Gemini CLI |
| [Configuration](guide/configuration.md) | Every key in `~/.browsentic/config.json` |
| [Approvals](guide/approvals.md) | What asks before it acts, and how to change that |
diff --git a/docs/guide/README.md b/docs/guide/README.md
index 2c94981..cb3dfd2 100644
--- a/docs/guide/README.md
+++ b/docs/guide/README.md
@@ -33,7 +33,7 @@ service.
| | |
| --- | --- |
-| [Choosing an agent](agents.md) | Claude Code, Codex or Antigravity — switching, and what each needs |
+| [Choosing an agent](agents.md) | Claude Code, Codex, Antigravity or Grok Build — switching, and what each needs |
| [MCP clients](mcp-clients.md) | Optional: registering Browsentic with Claude Code, Cursor, Zed, Codex or Gemini CLI |
| [Configuration](configuration.md) | Every key in `~/.browsentic/config.json` |
| [Approvals](approvals.md) | The gate — what asks first, and how to tune it |
diff --git a/docs/guide/agents.md b/docs/guide/agents.md
index 631e3c0..430e9ee 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. Four are supported, and switching
-is a click.
+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.
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 four
+## The five
-| | Claude Code | Codex | Antigravity | Mistral Vibe (beta) |
-| --- | --- | --- | --- | --- |
-| Vendor | Anthropic | OpenAI | Google | Mistral AI |
-| Binary | `claude` | `codex` | `agy` | `vibe` |
-| 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` |
-| Default model | `claude-sonnet-5` | 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 |
-| 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 |
+| | 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 |
-All four get the same system prompt, the same `browsentic` MCP server pointed back at the daemon,
+All five 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.
@@ -76,6 +76,21 @@ Pressing the button — or `browsentic agent fix antigravity` — appends exactl
the rest of that file alone. Nothing is written until you press it. If you have a `deny` rule
covering the same tools, Browsentic will not overrule it — remove it yourself.
+### Grok Build is in beta
+
+Browsentic's Grok runner was checked against `grok` 1.0.40 up to the model's first reply: every
+flag it passes, the containment, the browser tools reaching a run, and each error Grok reports. A
+whole conversation has not been run end to end yet, because the account it was built on was
+rate-limited before the model answered. Expect rough edges, and please report them.
+
+- **Sign in first.** Run `grok login`, or set `XAI_API_KEY`. Until then the popup shows *needs setup*.
+- **A free Grok account is rate-limited.** Grok retries quietly for several minutes before it gives
+ up, so a run can sit silent that long before it fails with *xAI did not answer*.
+- **It stays out of your other tools.** Grok normally loads Claude Code's and Cursor's MCP servers
+ and keeps a memory across sessions. A Browsentic run switches both off, so a page cannot reach
+ those servers or leave anything behind for your next Grok session. MCP servers you set up in
+ Grok itself still load; see [Spawn containment](../internals/guardrails.md#spawn-containment).
+
---
## Per-agent settings
@@ -89,7 +104,8 @@ In `~/.browsentic/config.json`:
"claude": { "bin": "/opt/homebrew/bin/claude", "model": "claude-sonnet-5", "effort": "high" },
"codex": { "bin": "codex", "model": "gpt-5.6-terra" },
"antigravity": { "bin": "agy" },
- "vibe": { "bin": "vibe" }
+ "vibe": { "bin": "vibe" },
+ "grok": { "bin": "grok", "model": "grok-4.7" }
}
}
```
@@ -113,10 +129,12 @@ Claude runner's settings.
| Symptom | Fix |
| --- | --- |
| `AGENT_MISSING` | The daemon's `PATH` differs from your shell's. Set `agents.<name>.bin` to an absolute path. |
-| `AGENT_NEEDS_PERMISSION` | Antigravity has no rule for Browsentic's tools. Press the button, or `browsentic agent fix antigravity`. |
+| `AGENT_NEEDS_PERMISSION` | Antigravity has no rule for Browsentic's tools: press the button, or `browsentic agent fix antigravity`. Grok Build is not signed in: run `grok login`. |
| Codex: "not logged in" | The daemon inherits no session. Run `codex login`, then retry. |
| "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. |
+| `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 9783a37..0ed82d1 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` or `vibe` |
+| `agent` | `claude` | Which CLI the side panel runs on: `claude`, `codex`, `antigravity`, `vibe` or `grok` |
| `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/features/conversations.md b/docs/guide/features/conversations.md
index 43280bf..2c0ca95 100644
--- a/docs/guide/features/conversations.md
+++ b/docs/guide/features/conversations.md
@@ -105,7 +105,7 @@ plus whether it can resume where it left off.
The card also shows token counts, straight from the agent CLI's own reporting: roughly how many
tokens the model's context window held after its last reply, and how many it generated on the last
-run. Claude Code and Codex report these; Antigravity does not, and the card says so.
+run. Claude Code, Codex and Grok Build report these; Antigravity does not, and the card says so.
It is answered by the extension itself, without waking an agent, so it also works mid-run. The card
describes what this browser holds; the agent's own working memory lives with the agent.
diff --git a/docs/guide/features/skills.md b/docs/guide/features/skills.md
index 4995e9c..19ade9e 100644
--- a/docs/guide/features/skills.md
+++ b/docs/guide/features/skills.md
@@ -89,7 +89,7 @@ browsentic skills # everything the router can see, tagged with where it came
The `/` picker also lists the skills the active agent CLI keeps for itself — Claude Code's
`~/.claude/skills/`, Codex's `~/.codex/skills/` and `~/.codex/prompts/`, the roots in Antigravity's
-`skills.txt`. Picking one attaches it to that message: the daemon reads the file at spawn time and
+`skills.txt`, and Grok Build's `~/.grok/skills/`, `~/.agents/skills/` and the Claude Code skills it also loads. Picking one attaches it to that message: the daemon reads the file at spawn time and
appends it to the system prompt, clearly marked, with a note that browser tools are all the run
has.
diff --git a/docs/guide/first-run.md b/docs/guide/first-run.md
index a13f1c9..4d209a9 100644
--- a/docs/guide/first-run.md
+++ b/docs/guide/first-run.md
@@ -72,6 +72,6 @@ Check in this order:
## Where to go next
- **[Features](features/)** — one page per capability
-- **[Choosing an agent](agents.md)** — if you would rather run Codex or Antigravity
+- **[Choosing an agent](agents.md)** — if you would rather run Codex, Antigravity or Grok Build
- **[Configuration](configuration.md)** — `~/.browsentic/config.json`
- **[Limits](limits.md)** — worth reading early rather than discovering
diff --git a/docs/guide/install.md b/docs/guide/install.md
index cd157c2..d172efc 100644
--- a/docs/guide/install.md
+++ b/docs/guide/install.md
@@ -14,7 +14,7 @@ AI agent you already run locally.
| --- | --- | --- |
| **Node** | 20 or newer | `node --version` |
| **Browser** | Chrome, or another Chromium browser (Edge, Brave, Arc) | — |
-| **Agent** | One of [Claude Code](https://claude.com/claude-code), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google/docs/cli/install) or [Mistral Vibe](https://github.com/mistralai/mistral-vibe) (beta) on your `PATH`, logged in | `claude --version`, `codex --version`, `agy --version` |
+| **Agent** | One of [Claude Code](https://claude.com/claude-code), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google/docs/cli/install), [Mistral Vibe](https://github.com/mistralai/mistral-vibe) (beta) or [Grok Build](https://docs.x.ai/build/overview) (beta) on your `PATH`, logged in | `claude --version`, `codex --version`, `agy --version`, `vibe --version`, `grok --version` |
Two things worth knowing before you start:
@@ -22,8 +22,8 @@ Two things worth knowing before you start:
instruction, so it is the one thing to have ready before your first run. See
[Choosing an agent](agents.md). The only setup that needs no CLI is driving the browser solely
from an [MCP client](mcp-clients.md), which is optional and spawns nothing.
-- **Only one of the three is needed.** Browsentic checks all three and tells you in the popup which
- are installed. Switching is a click.
+- **Only one of them is needed.** Browsentic checks every one and tells you in the popup which are
+ installed. Switching is a click.
---
diff --git a/docs/guide/limits.md b/docs/guide/limits.md
index 8038acc..33e4d81 100644
--- a/docs/guide/limits.md
+++ b/docs/guide/limits.md
@@ -63,11 +63,12 @@ contains it with whatever levers that CLI offers, and they are not equal:
| Agent | Containment |
| --- | --- |
-| Claude Code | A per-run tool allowlist plus an explicit deny list — the strongest of the three |
+| Claude Code | A per-run tool allowlist plus an explicit deny list — the strongest of them |
| Codex | No per-run tool list; the read-only sandbox is the whole containment, so it can still read any file you can |
| Antigravity | No tool list and no sandbox flag; its built-in tools are governed by your own CLI settings |
+| Grok Build (beta) | A per-run tool list, approvals that refuse anything not granted up front, and a sandbox that keeps its writes in its own folder; MCP servers you set up in Grok itself still load |
-The environment is sealed for all three — cloud keys, registry tokens and database URLs inherited
+The environment is sealed for all of them — cloud keys, registry tokens and database URLs inherited
from your shell are removed before the spawn, keeping only what that agent needs to authenticate.
Details in [internals/guardrails.md](../internals/guardrails.md#spawn-containment).
diff --git a/docs/guide/mac-app.md b/docs/guide/mac-app.md
index 2272b65..5b0a94c 100644
--- a/docs/guide/mac-app.md
+++ b/docs/guide/mac-app.md
@@ -65,7 +65,7 @@ The tabs float at the top; ⌘1–⌘7 switch between them.
| --- | --- |
| **Overview** | Turn the daemon on and off with the power button, restart it, see its address, version and whether the extension is connected and in sync. Copy the extension’s path, or open `chrome://extensions` in your browser with the path already on the clipboard |
| **Browsers** | Get a [pairing code](pair.md) with a live countdown, see every paired browser, unpair one or all |
-| **Agents** | See which of Claude Code, Codex and Antigravity are ready, [switch](agents.md) between them, pick a model, install a missing one, or let Browsentic fix what one still needs |
+| **Agents** | See which of Claude Code, Codex, Antigravity and Grok Build are ready, [switch](agents.md) between them, pick a model, install a missing one, or let Browsentic fix what one still needs |
| **Skills** | Every [skill](features/skills.md) the router can see and which folder it came from |
| **Activity** | Your standing [approvals](approvals.md), forgettable per site, and the downloads agents captured |
| **Logs** | `~/.browsentic/daemon.log`, followed live |
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index 56fa110..712a9c7 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -50,12 +50,15 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d
| Symptom | Cause | Fix |
| --- | --- | --- |
-| `AGENT_MISSING` | The chosen CLI is not on the *daemon's* `PATH` | `browsentic agent` to see all three; set `agents.<name>.bin` to an absolute path in `config.json` |
+| `AGENT_MISSING` | The chosen CLI is not on the *daemon's* `PATH` | `browsentic agent` to see every agent; set `agents.<name>.bin` to an absolute path in `config.json` |
| `AGENT_NEEDS_PERMISSION` | Antigravity has no rule allowing Browsentic's MCP tools | Press the button in the popup, or `browsentic agent fix antigravity` |
+| `AGENT_NEEDS_PERMISSION` for Grok Build | It is not signed in | `grok login`, or set `XAI_API_KEY` |
| "does not understand the flags Browsentic uses" | The agent CLI is too old | Update it |
| Mistral Vibe fails with *has no API key* | Vibe was never set up, or its key lives only in a shell the daemon was not started from | `vibe --setup`, which stores it in `~/.vibe/.env` |
| Antigravity answers but never touches the page | Its permission rule was removed | `browsentic agent` — it reports *needs setup* again |
| Codex fails with "not logged in" | The daemon inherits no session | `codex login`, then retry |
+| 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 |
+| `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/agent-runs.md b/docs/internals/agent-runs.md
index 5c09d51..d07a451 100644
--- a/docs/internals/agent-runs.md
+++ b/docs/internals/agent-runs.md
@@ -81,20 +81,24 @@ directory and any files that CLI reads from disk. A shared driver (`runners/driv
spawning, the abort wiring and the line reading; the runner only decides *what to say* and *how to
read the answer back*.
-**Adding a fourth agent is one file plus one line in `runners/index.ts`.**
+**Adding an agent is one file plus one line in `runners/index.ts`.**
Every runner is given the same four things, by whichever mechanism its CLI supports:
-| | Claude Code | Codex | Antigravity |
-| --- | --- | --- | --- |
-| Run | `claude -p --output-format stream-json` | `codex exec --json` | `agy -p --output-format stream-json` |
-| MCP server | `--mcp-config` + `--strict-mcp-config` | `-c mcp_servers.browsentic.*`, with `default_tools_approval_mode="approve"` — headless Codex refuses any MCP call it would have prompted for | `.agents/mcp_config.json` in its cwd |
-| System prompt | `--append-system-prompt` | `-c developer_instructions` | `AGENTS.md` in its cwd |
-| Follow-up turns | `--resume <session>` | `exec resume <thread>` | `--conversation <id>` |
-| Kept off the machine by | `--allowedTools` + `--disallowedTools` | `-c sandbox_mode="read-only"`, `-c approval_policy="never"` | its own permission rules |
+| | Claude Code | Codex | Antigravity | Grok Build |
+| --- | --- | --- | --- | --- |
+| Run | `claude -p --output-format stream-json` | `codex exec --json` | `agy -p --output-format stream-json` | `grok -p --output-format streaming-json` |
+| MCP server | `--mcp-config` + `--strict-mcp-config` | `-c mcp_servers.browsentic.*`, with `default_tools_approval_mode="approve"` — headless Codex refuses any MCP call it would have prompted for | `.agents/mcp_config.json` in its cwd | `.grok/config.toml` in its cwd, loaded with `GROK_FOLDER_TRUST=0`, and approved with `--allow MCPTool(browsentic__*)` |
+| System prompt | `--append-system-prompt` | `-c developer_instructions` | `AGENTS.md` in its cwd | `--rules` |
+| Follow-up turns | `--resume <session>` | `exec resume <thread>` | `--conversation <id>` | `--session-id <uuid>` names it, `--resume <uuid>` continues it, in a folder named after it |
+| Kept off the machine by | `--allowedTools` + `--disallowedTools` | `-c sandbox_mode="read-only"`, `-c approval_policy="never"` | its own permission rules | `--tools`, `--permission-mode dontAsk`, `--deny`, `--sandbox workspace` |
+
+Grok reaches MCP tools only through two meta-tools, `search_tool` and `use_tool`, under a
+`browsentic__` prefix; the system prompt it is given says so, because the skills name tools the way
+the server lists them.
**Conversation continuity** is what makes "now click the second one" work: the runner reports
-whatever session id its CLI established (`session_id`, `thread_id`, `conversation_id`) and gets it
+whatever session id its CLI established (`session_id`, `thread_id`, `conversation_id`, `sessionId`) and gets it
back on the next turn. Session ids are agent-scoped — switching agents drops the held conversation
rather than handing one agent another's id.
diff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.md
index bdfbcd4..1c6ea2a 100644
--- a/docs/internals/guardrails.md
+++ b/docs/internals/guardrails.md
@@ -314,14 +314,17 @@ Flags are the only lever those CLIs offer. That is worth having, but it is a **r
enforcement**: a dropped flag, a renamed option, or a new runner written in a hurry leaves no trace at
runtime and no failing check.
-So `vetPlan()` runs at `launch()` — the one place all three runners pass through — before `spawn()`.
+So `vetPlan()` runs at `launch()` — the one place every runner passes through — before `spawn()`.
A plan that has lost its containment does not start. It is pure, so the test harness can assert every
runner's real plan without spawning anything.
-It checks: required arguments present, `--flag value` pairs correct, every tool in the deny list
-actually named, required workspace files written, and no argument matching `FORBIDDEN` —
-`--dangerously*`, `--yolo`, `--full-auto`, `--no-sandbox`, `--allow-all`, `danger-full-access`,
-`--sandbox=workspace-write`, a `sandbox_mode=` or `approval_policy=` override that is not `"read-only"` / `"never"`,
+It checks: required arguments present; `--flag value` pairs correct, with no later repeat of the
+flag saying otherwise (a CLI takes the last one); every tool in the deny list actually named; an
+allowlist flag present, non-empty and naming nothing beyond what the runner may switch on; the
+environment switches a CLI only takes from its environment set; required workspace files written;
+and no argument matching `FORBIDDEN` — `--dangerously*`, `--yolo`, `--always-approve`, `--full-auto`,
+`--no-sandbox`, `--allow-all`, `danger-full-access`, `--sandbox=workspace-write` or `--sandbox=off`, a
+`sandbox_mode=` or `approval_policy=` override that is not `"read-only"` / `"never"`,
`--permission-mode=bypassPermissions`, and friends. Every pattern is
checked against every runner, not just the one that owns the flag: the cost is nothing and it covers
the runner nobody has written yet.
@@ -341,6 +344,51 @@ type LocalTools = 'allowlist' | 'sandbox' | 'host'
| **Codex** | `sandbox` | No per-run tool list; the read-only sandbox is the whole containment, **so the agent can still read any file the user can** |
| **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 |
+
+#### Grok Build, and why not always-approve
+
+Headless Grok is usually run with `--always-approve`, which hands it the machine. Browsentic uses
+`--permission-mode dontAsk` instead: only what was allowed up front runs, and that is one rule,
+`MCPTool(browsentic__*)`. Everything else is layered on top, and each layer is a flag or a variable
+`vetPlan()` can see:
+
+| Layer | Run | Task |
+| --- | --- | --- |
+| Built-in tools (`--tools`) | `todo_write`, or `web_search,web_fetch` when researching | `todo_write`, or `read_file` when handed a file |
+| Deny rules (`--deny`) | `Bash`, `Edit`, `Write`, `Read` | `MCPTool`, `Bash`, `Edit`, `Write` |
+| Sandbox (`--sandbox`) | `workspace` — writes only to the run's own folder, `~/.grok` and temp | `read-only` |
+| Environment | `GROK_MEMORY=0`, `GROK_CLAUDE_MCPS_ENABLED=false`, `GROK_CURSOR_MCPS_ENABLED=false` | the same |
+
+Why each one is there:
+
+- **`--tools` is the real allowlist**, and an empty one means *every* tool — the shell and file
+ editing among them. So a run that needs no built-in names `todo_write`, which touches nothing, and
+ `vetPlan()` refuses a missing or empty list.
+- **Deny rules beat every allow rule Grok merges in**, and Grok merges a lot: its own config, the
+ project's, and Claude Code's `~/.claude/settings*.json`. `Read` also refuses `use_tool`'s
+ file-backed arguments, which would otherwise turn any JSON file on disk into a tool call's input.
+ A task's bare `MCPTool` deny refuses every MCP call from any server.
+- **The sandbox is `workspace`, not `read-only`**, because on Linux `read-only` also blocks the
+ network of child processes, and the `browsentic` MCP server is one: it reaches the daemon over
+ loopback. The sandbox confines writes; it does not stop reads, which is what the first two layers are for.
+- **Grok loads Claude Code's and Cursor's MCP servers by default** — including a `browsentic` entry
+ added for Claude Code, which reaches the browser without a run's gate. The environment switches drop
+ them. The run's own `browsentic` server is written to a project `.grok/config.toml`, which also
+ shadows any user entry of the same name.
+- **Its memory is off**, so what a page said cannot resurface in the user's next Grok session.
+
+A project config in a folder nobody trusted is skipped without a word, so a run sets
+`GROK_FOLDER_TRUST=0` for its own process. `--trust` would record every conversation folder in the
+user's `~/.grok/trusted_folders.toml` instead.
+
+The reader checks what Grok actually did. Grok lists its toolset before the model is called, and a
+run offered anything beyond the meta-tools, `todo_write` and the web tools fails with `AGENT_UNSAFE`
+before the model sees it. The process is stopped, not left running.
+
+**What remains:** MCP servers the user configured in Grok itself, natively or through a plugin, still
+load. Their tools run only if the user approved them ahead of time — but Grok's approvals include
+rules merged from Claude Code's settings.
`localTools` records which case each runner is in, and the note is logged once per run, so the weak
one is **visible in the log rather than assumed away**.
@@ -349,7 +397,7 @@ one is **visible in the log rather than assumed away**.
`run` drives the browser. `task` is a one-shot — summarizing an attached file, turning a raw
recording trace into steps — that must not reach the browser at all, which is asserted by requiring
-`{"mcpServers":{}}` (or `mcp_servers={}`) in its argv. `Read` is deliberately left out of `task`'s
+`{"mcpServers":{}}` (or `mcp_servers={}`, or Grok's `--deny MCPTool`) in its argv. `Read` is deliberately left out of `task`'s
deny list, because some tasks are handed a file in the scratch workspace.
### Sealing the environment
@@ -369,6 +417,7 @@ Each agent keeps only the prefixes it needs to authenticate:
| Codex | `OPENAI_`, `CODEX_`, `AZURE_OPENAI_` |
| Antigravity | `GEMINI_`, `GOOGLE_`, `ANTIGRAVITY_` |
| Mistral Vibe | `MISTRAL_`, `VIBE_` |
+| Grok Build | `XAI_`, `GROK_` |
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
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index bf817b7..f440b6a 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -72,7 +72,7 @@ See [guide/pair.md](../guide/pair.md).
| Command | Does |
| --- | --- |
| `browsentic agent` | Show which agent runs the side panel, and which are installed |
-| `browsentic agent <name>` | Switch to `claude`, `codex`, `antigravity` or `vibe` |
+| `browsentic agent <name>` | Switch to `claude`, `codex`, `antigravity`, `vibe` or `grok` |
| `browsentic agent fix <name>` | Let Browsentic fix what that agent still needs |
| `browsentic agent model <name> [model]` | Pin that agent’s model in `config.json`; omit the model to go back to the CLI’s own default |
diff --git a/docs/reference/errors.md b/docs/reference/errors.md
index 2b074b9..d86f326 100644
--- a/docs/reference/errors.md
+++ b/docs/reference/errors.md
@@ -66,8 +66,9 @@ repeatedly: failures carry the *fix* in the message, and a failed tool call neve
| Code | Origin | Meaning and next move |
| --- | --- | --- |
| `AGENT_MISSING` | Runner | The chosen agent's binary is not on the *daemon's* `PATH`. Set `agents.<name>.bin` to an absolute path |
-| `AGENT_NEEDS_PERMISSION` | Runner | Antigravity has no rule allowing Browsentic's MCP tools. `browsentic agent fix antigravity` |
+| `AGENT_NEEDS_PERMISSION` | Runner | Antigravity has no rule allowing Browsentic's MCP tools (`browsentic agent fix antigravity`), or Grok Build is not signed in (`grok login`) |
| `AGENT_UNUSABLE` | Runner | The CLI is present but cannot run — usually too old for the flags Browsentic passes |
+| `AGENT_UNSAFE` | Runner | The run was stopped before the agent could act on the machine: its plan had lost its containment, which is a bug in Browsentic, or Grok Build offered tools Browsentic never asks for. Update both, and report it |
## Guardrails