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): OpenCode beside the other seven, why it needs a provider signed in when Zen's free models refuse a contained run, and what its config merge nearly let through

Shahriar056a42304d25
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 6bfd6c6..159f952 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -42,7 +42,7 @@ body:
attributes:
label: Agent
description: Which agent CLI runs your side panel, if the bug involves a run.
- placeholder: claude / codex / agy / vibe / grok / cursor-agent / qwen, and its version
+ placeholder: claude / codex / agy / vibe / grok / cursor-agent / qwen / opencode, and its version
- type: input
id: environment
attributes:
diff --git a/SECURITY.md b/SECURITY.md
index e341b06..7317b7a 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -49,8 +49,8 @@ other liability arising from the software or its use. In plain language, that me
the action; deciding is yours. Actions taken in your browser — purchases, submissions,
messages, deletions — are actions taken on your accounts, by you.
- **The agent is not part of this project.** Browsentic spawns whichever agent CLI you chose —
- Claude Code, Codex, Antigravity, Mistral Vibe, Grok Build, Cursor CLI or Qwen Code — and
- contains each as well as its own flags allow, but their behaviour,
+ Claude Code, Codex, Antigravity, Mistral Vibe, Grok Build, Cursor CLI, Qwen Code or OpenCode —
+ and contains each as well as its own flags allow, but their behaviour,
their terms, and what they do with your prompts are governed by their vendors, not by this
repository.
- **Automating a website may breach that website's terms of service.** Whether a site permits
diff --git a/docs/README.md b/docs/README.md
index 049e65b..0200636 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) | The seven agent CLIs the side panel can run on |
+| [Choosing an agent](guide/agents.md) | The eight agent CLIs the side panel can run on |
| [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 abd1f91..6636f57 100644
--- a/docs/guide/README.md
+++ b/docs/guide/README.md
@@ -33,7 +33,7 @@ service.
| | |
| --- | --- |
-| [Choosing an agent](agents.md) | The seven agent CLIs the side panel can run on — switching, and what each needs |
+| [Choosing an agent](agents.md) | The eight agent CLIs the side panel can run on — 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 73919cc..3323306 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. Seven are supported — Mistral Vibe,
-Grok Build, Cursor CLI and Qwen Code in beta — and switching is a click.
+The side panel runs on an agent CLI you already have logged in. Eight are supported — Mistral Vibe,
+Grok Build, Cursor CLI, Qwen Code and OpenCode 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 seven
+## The eight
-| | Claude Code | Codex | Antigravity | Mistral Vibe (beta) | Grok Build (beta) | Cursor CLI (beta) | Qwen Code (beta) |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| Vendor | Anthropic | OpenAI | Google | Mistral AI | xAI | Anysphere | Alibaba |
-| Binary | `claude` | `codex` | `agy` | `vibe` | `grok` | `cursor-agent` | `qwen` |
-| 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` | `npm i -g @qwen-code/qwen-code` |
-| 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 | 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]` | none — the model id is the only lever |
-| 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 | `--safe-mode`, which drops every setting of your own, plus deny rules for the shell, the disk and the tools that reach either |
+| | Claude Code | Codex | Antigravity | Mistral Vibe (beta) | Grok Build (beta) | Cursor CLI (beta) | Qwen Code (beta) | OpenCode (beta) |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Vendor | Anthropic | OpenAI | Google | Mistral AI | xAI | Anysphere | Alibaba | Anomaly |
+| Binary | `claude` | `codex` | `agy` | `vibe` | `grok` | `cursor-agent` | `qwen` | `opencode` |
+| 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` | `npm i -g @qwen-code/qwen-code` | `npm i -g opencode-ai` |
+| 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 | 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]` | none — the model id is the only lever | a variant the model defines, e.g. `high` or `max` |
+| 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 | `--safe-mode`, which drops every setting of your own, plus deny rules for the shell, the disk and the tools that reach either | a per-run agent whose rules deny every tool not named for it, so the model is never offered the shell, the disk or another server's tools |
-All seven get the same system prompt, the same `browsentic` MCP server pointed back at the daemon,
+All eight 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.
@@ -174,6 +174,44 @@ Expect rough edges, and please report them.
---
+### OpenCode is in beta
+
+Browsentic's OpenCode runner was checked against `opencode` 1.18.32 with a stand-in for the model
+provider: every flag and setting it passes, the containment under a user config written to break
+it, the browser tools reaching a run, a follow-up turn resuming, and each error OpenCode reports.
+What has not been through it yet is a real model driving a real page, because OpenCode Zen's free
+models refuse a contained run and no paid provider was signed in where it was built. Expect rough
+edges, and please report them.
+
+- **Sign in to a provider first.** Run `opencode auth login`. Zen's free models answer only
+ requests that carry OpenCode's own built-in tools, and a Browsentic run carries the browser's
+ alone, so they refuse it with *free tier can only be used from within OpenCode*. Until OpenCode
+ has a login, or a provider in its config such as a local model, the popup shows *needs setup*.
+- **Models are `provider/model`**, spelled as `opencode models` lists them.
+- **A key in the environment does not reach a run.** Only `OPENCODE_*` does; `ANTHROPIC_API_KEY`
+ and the like are sealed away. `opencode auth login` keeps the key in OpenCode's own file instead,
+ which a run reads as usual.
+- **Your OpenCode settings are read, and cannot widen a run.** Your providers, models and
+ `~/.config/opencode/AGENTS.md` apply. The run is an agent of Browsentic's own whose rules deny
+ every tool not named for it, so your permission rules, custom tools and the MCP servers you set up
+ in OpenCode itself are hidden from the model — those servers still start. External plugins and
+ project config are off for the run.
+- **Sharing is off.** A `"share": "auto"` of your own would publish every browsing session to a
+ public link, so a run switches sharing off.
+- **Its sessions are kept apart from yours.** Runs and one-shots go into a session store under
+ `~/.browsentic`, not into `opencode session list`.
+- **Replies arrive a part at a time.** OpenCode's stream carries each finished part rather than
+ tokens, as Vibe's does.
+- **A tool result is cut at 100 KB** rather than OpenCode's own 50 KB, which a whole-page snapshot
+ can pass. Past that, the prompt asks for smaller reads, because the saved copy OpenCode points to
+ cannot be opened in a run.
+- **Effort is a variant.** `agents.opencode.effort` is passed as `--variant`, whose names each model
+ defines; one a model lacks is ignored.
+- **The run is stopped if a local tool ran.** OpenCode reports every tool call, and one that ran
+ outside the browser ends the run with `AGENT_UNSAFE`.
+
+---
+
## Per-agent settings
In `~/.browsentic/config.json`:
@@ -188,7 +226,8 @@ In `~/.browsentic/config.json`:
"vibe": { "bin": "vibe" },
"grok": { "bin": "grok", "model": "grok-4.7" },
"cursor": { "bin": "cursor-agent", "model": "composer-2.5" },
- "qwen": { "bin": "qwen", "model": "qwen3-coder-plus" }
+ "qwen": { "bin": "qwen", "model": "qwen3-coder-plus" },
+ "opencode": { "bin": "opencode", "model": "anthropic/claude-sonnet-5" }
}
}
```
@@ -212,7 +251,7 @@ 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`. Grok Build is not signed in: run `grok login`. Qwen Code has no model provider: run `qwen` and use `/auth`. |
+| `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`. Qwen Code has no model provider: run `qwen` and use `/auth`. OpenCode is signed in to no provider: run `opencode auth login`. |
| Codex: "not logged in" | The daemon inherits no session. Run `codex login`, then retry. |
| Codex answers about the page without opening it, or from a web search | Update Browsentic. Codex hides the browser tools until the model searches for them, and an older Browsentic left Codex's own web search switched on, which the model reached for first. |
| Mistral Vibe: a follow-up turn says *this agent run is no longer active* | Update Browsentic, then start a new conversation. An older one gave each turn its own folder, and Vibe keeps re-reading the first turn's, so a conversation begun before the update stays broken. |
@@ -225,6 +264,10 @@ Claude runner's settings.
| Qwen Code: *No auth type is selected* | Qwen has no provider configured, and its OAuth free tier has ended. Run `qwen` and use `/auth`, or export `OPENAI_API_KEY` with `OPENAI_BASE_URL`. |
| Qwen Code cannot find a key you have exported | Only `QWEN_*`, `DASHSCOPE_*`, `BAILIAN_*` and `OPENAI_*` reach a run; `ANTHROPIC_*` and `GEMINI_*` are sealed away. Point Qwen at one of the first four. |
| `AGENT_UNSAFE`: *Qwen Code registered …* or *loaded the MCP server …* | Qwen's own `init` line named a tool or a server Browsentic denied, so the run was stopped. Update Qwen Code and Browsentic, and report it if it persists. |
+| OpenCode: *free models refuse a run whose tools Browsentic has narrowed to the browser* | Zen's free tier serves only requests carrying OpenCode's own tools. Run `opencode auth login`, then pick that provider's model in the popup. |
+| OpenCode: *could not start this turn* | Usually a model OpenCode does not know. Pick one as `opencode models` lists it, `provider/model`. |
+| OpenCode cannot find a key you have exported | Only `OPENCODE_*` reaches a run. Run `opencode auth login` instead, which keeps the key in OpenCode's own file. |
+| `AGENT_UNSAFE`: *OpenCode ran its own … tool* | A tool outside the browser ran despite the run's rules, so the run was stopped. Update OpenCode and Browsentic, and report it. |
---
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index 82b9ea8..4344a70 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`, `grok`, `cursor` or `qwen` |
+| `agent` | `claude` | Which CLI the side panel runs on: `claude`, `codex`, `antigravity`, `vibe`, `grok`, `cursor`, `qwen` or `opencode` |
| `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 3fc27a5..c8524d6 100644
--- a/docs/guide/features/conversations.md
+++ b/docs/guide/features/conversations.md
@@ -105,8 +105,8 @@ 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, Codex, Grok Build, Cursor CLI and Qwen Code report these; Antigravity and Mistral Vibe
-do not, and the card says so.
+run. Claude Code, Codex, Grok Build, Cursor CLI, Qwen Code and OpenCode report these; Antigravity and
+Mistral Vibe do 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 59512ad..42eb286 100644
--- a/docs/guide/features/skills.md
+++ b/docs/guide/features/skills.md
@@ -98,6 +98,7 @@ The `/` picker also lists the skills the active agent CLI keeps for itself:
| Grok Build | `~/.grok/skills/`, `~/.agents/skills/`, and the Claude Code skills it also loads |
| Cursor CLI | `~/.cursor/skills/`, `~/.agents/skills/` |
| Qwen Code | `~/.qwen/skills/`, `~/.agents/skills/` |
+| OpenCode | `~/.config/opencode/skills/` (and `skill/`), `~/.opencode/skills/`, `~/.agents/skills/`, `~/.claude/skills/` |
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
diff --git a/docs/guide/install.md b/docs/guide/install.md
index 36b99d8..351a61b 100644
--- a/docs/guide/install.md
+++ b/docs/guide/install.md
@@ -15,7 +15,7 @@ AI agent you already run locally.
| **Node** | 20 or newer | `node --version` |
| **Browser** | Chrome or another Chromium browser (Edge, Brave, Arc), or Firefox 140 or newer | — |
| **System** | macOS, Windows or Linux. macOS also has an [app](mac-app.md) | — |
-| **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), [Grok Build](https://docs.x.ai/build/overview) (beta), [Cursor CLI](https://cursor.com/docs/cli/overview) (beta) or [Qwen Code](https://qwenlm.github.io/qwen-code-docs/en/) (beta) on your `PATH`, logged in | `claude --version`, `codex --version`, `agy --version`, `vibe --version`, `grok --version`, `cursor-agent --version`, `qwen --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), [Grok Build](https://docs.x.ai/build/overview) (beta), [Cursor CLI](https://cursor.com/docs/cli/overview) (beta), [Qwen Code](https://qwenlm.github.io/qwen-code-docs/en/) (beta) or [OpenCode](https://opencode.ai/docs/cli/) (beta) on your `PATH`, logged in | `claude --version`, `codex --version`, `agy --version`, `vibe --version`, `grok --version`, `cursor-agent --version`, `qwen --version`, `opencode --version` |
Two things worth knowing before you start:
diff --git a/docs/guide/limits.md b/docs/guide/limits.md
index bfce836..38ae6dc 100644
--- a/docs/guide/limits.md
+++ b/docs/guide/limits.md
@@ -70,14 +70,15 @@ contains it with whatever levers that CLI offers, and they are not equal:
| 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 |
| Cursor CLI (beta) | Per-run deny rules, where a deny beats every allow including your own; a kernel sandbox is asked for too, but it has no Windows backend and is not depended on |
| Qwen Code (beta) | `--safe-mode` drops every setting of your own — hooks, extensions, bundled skills, MCP servers, permission rules — and deny rules close the shell, the disk and the tools that reach either; because that mode also disables Qwen's own fail-closed tool allowlist, the run's startup line is read back and anything unexpected stops it |
+| OpenCode (beta) | A per-run agent whose rules open on a deny for every tool, applied after your own rules, so the model is offered only the browser; external plugins and project config are off, and MCP servers you set up in OpenCode itself still start, with their tools hidden |
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).
-## Four of the agents are beta
+## Five of the agents are beta
-Mistral Vibe, Grok Build, Cursor CLI and Qwen Code were built by reading each CLI and checking its
+Mistral Vibe, Grok Build, Cursor CLI, Qwen Code and OpenCode were built by reading each CLI and checking its
flags, its containment and its error texts — but none has carried a whole conversation end to end
yet, so the popup, the docs and the release notes say *beta*. What that means in practice:
@@ -87,7 +88,9 @@ yet, so the popup, the docs and the release notes say *beta*. What that means in
- Cursor is less fenced off on Windows, where its kernel sandbox has no backend;
- Qwen was written against its source rather than a running binary — no provider was configured on
the machine it was built on — and it needs one configured before it will answer at all;
-- the other three agents are untouched: the hooks the four share are covered by the spawn and
+- OpenCode needs a provider signed in, because Zen's free models refuse a run narrowed to the
+ browser, and its replies arrive a part at a time;
+- the other three agents are untouched: the hooks the five share are covered by the spawn and
drive tests.
[Choosing an agent](agents.md) has the per-agent detail. Please report what you find.
diff --git a/docs/guide/mac-app.md b/docs/guide/mac-app.md
index 2692309..fef5367 100644
--- a/docs/guide/mac-app.md
+++ b/docs/guide/mac-app.md
@@ -46,7 +46,7 @@ The app opens on six checks and runs them on its own:
| **Browsentic command** | `~/.browsentic/cli` holds the version this app carries | **Install** copies it there and writes the `browsentic` launcher to `~/.browsentic/bin` |
| **Browser extension** | the same version is unpacked at `~/browsentic/extension/chrome-mv3` | **Install** unpacks it |
| **A Chromium browser** | Chrome, Brave, Edge, Arc, Vivaldi, Opera or Chromium is installed | **Get Chrome** opens the download page. Advisory — it does not block you |
-| **An AI agent** | One of `claude`, `codex`, `agy`, `vibe`, `grok`, `cursor-agent` or `qwen` is on your `PATH` | **Install Claude Code** runs `npm i -g @anthropic-ai/claude-code`. Advisory |
+| **An AI agent** | One of `claude`, `codex`, `agy`, `vibe`, `grok`, `cursor-agent`, `qwen` or `opencode` is on your `PATH` | **Install Claude Code** runs `npm i -g @anthropic-ai/claude-code`. Advisory |
**Set up everything** installs the first three in one click. A browser and an agent are yours to
choose, so each has a button of its own. When everything required is in place the app moves on by
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index e7e203f..c92a901 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -68,6 +68,10 @@ Those three answer most questions. The daemon log also lives at `~/.browsentic/d
| Qwen Code fails with *No auth type is selected* | Qwen has no provider configured, and its OAuth free tier ended on 2026-04-15 | Run `qwen` and use `/auth`, or export `OPENAI_API_KEY` with `OPENAI_BASE_URL` |
| Qwen Code cannot see an API key you exported | Only `QWEN_*`, `DASHSCOPE_*`, `BAILIAN_*` and `OPENAI_*` reach a run; the rest are sealed away | Point Qwen at one of those four providers |
| `AGENT_UNSAFE`: *Qwen Code registered …* / *loaded the MCP server …* | Qwen's own startup line named a tool or a server Browsentic denied, so the run was stopped before the model saw it | Update Qwen Code and Browsentic; report it if it persists |
+| OpenCode fails with *free models refuse a run whose tools Browsentic has narrowed to the browser* | OpenCode Zen's free tier serves only requests carrying OpenCode's own built-in tools | `opencode auth login`, then pick that provider's model in the popup |
+| OpenCode fails with *could not start this turn* | Usually a model OpenCode does not know | Pick one as `opencode models` lists it, `provider/model` |
+| OpenCode cannot see an API key you exported | Only `OPENCODE_*` reaches a run; the rest are sealed away | `opencode auth login`, which keeps the key in OpenCode's own file |
+| `AGENT_UNSAFE`: *OpenCode ran its own … tool* | A tool outside the browser ran despite the run's rules, so the run was stopped | Update OpenCode and Browsentic, and report it |
## Pages and tabs
diff --git a/docs/internals/agent-runs.md b/docs/internals/agent-runs.md
index 11428e1..9b8b557 100644
--- a/docs/internals/agent-runs.md
+++ b/docs/internals/agent-runs.md
@@ -85,13 +85,13 @@ read the answer back*.
Every runner is given the same five things, by whichever mechanism its CLI supports:
-| | Claude Code | Codex | Antigravity | Mistral Vibe | Grok Build | Cursor CLI | Qwen Code |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| Run | `claude -p --output-format stream-json` | `codex exec --json` | `agy -p --output-format stream-json` | `vibe --prompt … --output streaming --trust --agent ask` | `grok -p --output-format streaming-json` | `cursor-agent -p --output-format stream-json --stream-partial-output` | `qwen -p --output-format stream-json --include-partial-messages` |
-| 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 | `.vibe/config.toml` in a folder per conversation, every tool granted by name | `.grok/config.toml` in its cwd, loaded with `GROK_FOLDER_TRUST=0`, and approved with `--allow MCPTool(browsentic__*)` | `.cursor/mcp.json` in a folder per conversation, allowed as `Mcp(browsentic:*)` with every other server denied by name | `--mcp-config` + `--allowed-mcp-server-names`, under `--safe-mode`, which drops the ones on disk |
-| System prompt | `--append-system-prompt` | `-c developer_instructions` | `AGENTS.md` in its cwd | `AGENTS.md` beside its config | `--rules` | `AGENTS.md` in its cwd | `--append-system-prompt` |
-| Follow-up turns | `--resume <session>` | `exec resume <thread>` | `--conversation <id>` | `--resume <session>`, re-read from the folder the session began in | `--session-id <uuid>` names it, `--resume <uuid>` continues it, in a folder named after it | `--resume <session>` | `--session-id <uuid>` names it, `--resume <uuid>` continues it |
-| Kept off the machine by | `--allowedTools` + `--disallowedTools` | `-c sandbox_mode="read-only"`, `-c approval_policy="never"`, `-c features.multi_agent=false` | its own permission rules | `--enabled-tools`, which is an allowlist | `--tools`, `--permission-mode dontAsk`, `--deny`, `--sandbox workspace` | deny rules in `.cursor/cli.json`, plus `--sandbox enabled` | `--safe-mode`, `--exclude-tools`, `--approval-mode default` |
+| | Claude Code | Codex | Antigravity | Mistral Vibe | Grok Build | Cursor CLI | Qwen Code | OpenCode |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Run | `claude -p --output-format stream-json` | `codex exec --json` | `agy -p --output-format stream-json` | `vibe --prompt … --output streaming --trust --agent ask` | `grok -p --output-format streaming-json` | `cursor-agent -p --output-format stream-json --stream-partial-output` | `qwen -p --output-format stream-json --include-partial-messages` | `opencode run --format json --pure --agent browsentic-contained` |
+| 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 | `.vibe/config.toml` in a folder per conversation, every tool granted by name | `.grok/config.toml` in its cwd, loaded with `GROK_FOLDER_TRUST=0`, and approved with `--allow MCPTool(browsentic__*)` | `.cursor/mcp.json` in a folder per conversation, allowed as `Mcp(browsentic:*)` with every other server denied by name | `--mcp-config` + `--allowed-mcp-server-names`, under `--safe-mode`, which drops the ones on disk | `mcp.browsentic` in `OPENCODE_CONFIG_CONTENT`, each tool allowed by name on the run's own agent |
+| System prompt | `--append-system-prompt` | `-c developer_instructions` | `AGENTS.md` in its cwd | `AGENTS.md` beside its config | `--rules` | `AGENTS.md` in its cwd | `--append-system-prompt` | a file in a folder per conversation, named in the config's `instructions` — never the config itself, which OpenCode expands `{file:…}` in |
+| Follow-up turns | `--resume <session>` | `exec resume <thread>` | `--conversation <id>` | `--resume <session>`, re-read from the folder the session began in | `--session-id <uuid>` names it, `--resume <uuid>` continues it, in a folder named after it | `--resume <session>` | `--session-id <uuid>` names it, `--resume <uuid>` continues it | `--session <id>`, from a session store of Browsentic's own (`OPENCODE_DB`) |
+| Kept off the machine by | `--allowedTools` + `--disallowedTools` | `-c sandbox_mode="read-only"`, `-c approval_policy="never"`, `-c features.multi_agent=false` | its own permission rules | `--enabled-tools`, which is an allowlist | `--tools`, `--permission-mode dontAsk`, `--deny`, `--sandbox workspace` | deny rules in `.cursor/cli.json`, plus `--sandbox enabled` | `--safe-mode`, `--exclude-tools`, `--approval-mode default` | an agent whose permission opens on `"*": "deny"`, `--pure`, `OPENCODE_DISABLE_PROJECT_CONFIG`, `OPENCODE_DISABLE_SHARE` |
**Two CLIs do not put the browser tools in the model's list, and both are told so in the prompt.**
Grok reaches MCP tools only through two meta-tools, `search_tool` and `use_tool`, under a
diff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.md
index 43c40b1..75597d0 100644
--- a/docs/internals/guardrails.md
+++ b/docs/internals/guardrails.md
@@ -347,6 +347,7 @@ type LocalTools = 'allowlist' | 'sandbox' | 'host'
| **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 |
| **Qwen Code** | `allowlist` | `--allowed-tools mcp__browsentic` is what a run may call without being asked, and a headless turn refuses everything it would otherwise have prompted for. `--safe-mode` is what makes the rest hold: it drops the user's hooks, extensions, bundled skills, `settings.json` MCP servers, `.mcp.json` and permission rules, while keeping `--mcp-config` — an explicit per-invocation argument rather than ambient state. Its cost is that it also **silently ignores `--core-tools`**, the fail-closed allowlist over Qwen's twenty-one core tools, so the built-ins are closed with `--exclude-tools` deny rules instead. A deny list cannot be fail-closed, so the `init` line is read back: it names every tool and MCP server that actually registered, and the reader ends the run with `AGENT_UNSAFE` on anything Browsentic did not ask for, before the model has spoken |
| **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 |
+| **OpenCode** | `allowlist` | The run is an agent the config defines, whose permission ruleset opens on `"*": "deny"` and then allows each browser tool by name. OpenCode applies the last rule that matches and puts an agent's rules after the user's, so every other tool — built-in, custom, another MCP server's, or one a later release adds — is denied, and a tool denied outright is never offered to the model. `--pure` keeps plugins out, which run inside OpenCode and can answer its permission prompts. MCP servers the user set up in OpenCode itself still start, with their tools hidden |
#### Grok Build, and why not always-approve
@@ -392,6 +393,35 @@ before the model sees it. The process is stopped, not left running.
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.
+#### OpenCode, and why its agent has a name nobody would pick
+
+OpenCode takes its whole config as JSON in `OPENCODE_CONFIG_CONTENT`, so the MCP server, the ruleset
+and the agent they belong to exist only for the one process. `vetPlan()` reads that variable back:
+`envContains` requires `"*":"deny"` and `"share":"disabled"` in it, and a task's `"mcp":{}` as well.
+Beside it, `OPENCODE_DISABLE_PROJECT_CONFIG` keeps an `opencode.json` or `.opencode` folder above the
+workspace from loading, and `OPENCODE_DISABLE_SHARE` means a user's `"share": "auto"` cannot publish
+a browsing session to a public link.
+
+Three things about OpenCode shaped the rest, each measured against 1.18.32:
+
+- **An agent of the same name is merged, in the user's key order.** Someone who made an agent called
+ `browsentic` for their own use, with `{"*": "allow", "bash": "allow"}`, would keep their `"*"` first
+ and their `bash` after Browsentic's deny — and a shell command ran. So the run's agent is
+ `browsentic-contained`, a name nobody picks by accident, and the reader stops a run in which a tool
+ outside the browser completed.
+- **OpenCode expands `{env:…}` and `{file:…}` anywhere in its config**, escaped or not. The system
+ prompt carries page text, and a page that wrote `{file:~/.ssh/id_rsa}` would have had the file read
+ into it. So the prompt is a file the config's `instructions` names; instruction files are read as
+ they are.
+- **A read is matched against its path relative to the project root**, which is `/` for a folder
+ outside git and the repository when the home directory is one. A task handed a file may read its
+ scratch folder as seen from every ancestor of the workspace — but not from the workspace itself,
+ where `tmp/*` under a root of `/` would be the machine's `/tmp`.
+
+**What remains:** MCP servers the user set up in OpenCode itself still start for every run, with their
+tools hidden from the model. And the user's own `~/.config/opencode/AGENTS.md` is read, as Claude
+Code reads the user's `CLAUDE.md`.
+
`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**.
@@ -400,7 +430,8 @@ one is **visible in the log rather than assumed away**.
`run` drives the browser. `task` is a one-shot — the file analyst reading an attached file, the
captcha analyst looking at one round of a challenge, turning a raw recording trace into steps — that
must not reach the browser at all, which is asserted by
-requiring `{"mcpServers":{}}` (or `mcp_servers={}`, or Grok's `--deny MCPTool`) in its argv. `Read`
+requiring `{"mcpServers":{}}` (or `mcp_servers={}`, or Grok's `--deny MCPTool`) in its argv, or
+OpenCode's `"mcp":{}` and `"*":"deny"` in its config. `Read`
is deliberately left out of `task`'s deny list, because some tasks are handed a file in the scratch
workspace.
@@ -408,9 +439,10 @@ The file analyst adds three things to that. A file is screened before anything s
archive, an executable or an oversized file never reaches an agent at all. The one-shot is stopped
the moment its answer is in rather than left to exit, and its copy of the file is deleted. And the
session is not kept where the CLI allows it: Claude Code runs a task with
-`--no-session-persistence` and Codex with `--ephemeral`. Antigravity, Mistral Vibe, Grok Build,
-Cursor CLI and Qwen Code have no such switch, so a task's session stays in that CLI's own history,
-inside the per-mode task workspace it was started in.
+`--no-session-persistence` and Codex with `--ephemeral`. OpenCode has no such switch, but its runs
+and tasks both go into a session store under `~/.browsentic` (`OPENCODE_DB`) rather than the user's.
+Antigravity, Mistral Vibe, Grok Build, Cursor CLI and Qwen Code have neither, so a task's session
+stays in that CLI's own history, inside the per-mode task workspace it was started in.
### Sealing the environment
@@ -432,6 +464,7 @@ Each agent keeps only the prefixes it needs to authenticate:
| Grok Build | `XAI_`, `GROK_` |
| Cursor CLI | `CURSOR_` |
| Qwen Code | `QWEN_`, `DASHSCOPE_`, `BAILIAN_`, `OPENAI_` |
+| OpenCode | `OPENCODE_` |
Qwen Code is the awkward one: it authenticates through whichever provider it is pointed at, and the
documented mainstream setup is `OPENAI_API_KEY` with `OPENAI_BASE_URL` at a DashScope endpoint, so
@@ -440,11 +473,16 @@ The `anthropic` and `gemini` auth types Qwen also accepts are **not** widened fo
vendor's agent another vendor's key is what this exists to prevent, so `check()` reports a Qwen with
only `ANTHROPIC_API_KEY` set as *needs setup* rather than promising a login that cannot happen.
+OpenCode reads a dozen providers' keys from the environment, and keeping all of them would undo
+sealing for it altogether. It keeps its own logins in a file instead — `opencode auth login` writes
+it — so only `OPENCODE_` survives, and `check()` counts that file, a Zen key, or a provider declared
+in its config as signed in.
+
Sealing is also not absolute for Qwen, and it is worth saying so plainly: Qwen loads the first
`.env` it finds walking up from its working directory, then `~/.qwen/.env` and `~/.env`, for
variables not already present — so a key `sealEnv` stripped can come back from disk. It reaches the
model provider rather than the model, because the shell and file tools are denied, but the guarantee
-is weaker there than for the other six.
+is weaker there than for the other seven.
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 a879996..b940bc8 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`, `vibe`, `grok`, `cursor` or `qwen` |
+| `browsentic agent <name>` | Switch to `claude`, `codex`, `antigravity`, `vibe`, `grok`, `cursor`, `qwen` or `opencode` |
| `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 685f7f8..51284d9 100644
--- a/docs/reference/errors.md
+++ b/docs/reference/errors.md
@@ -66,9 +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`), Grok Build or Cursor CLI is not signed in (`grok login`, `cursor-agent login`), or Qwen Code has no model provider configured (`qwen`, then `/auth`) |
+| `AGENT_NEEDS_PERMISSION` | Runner | Antigravity has no rule allowing Browsentic's MCP tools (`browsentic agent fix antigravity`), Grok Build or Cursor CLI is not signed in (`grok login`, `cursor-agent login`), Qwen Code has no model provider configured (`qwen`, then `/auth`), or OpenCode is signed in to no provider (`opencode auth 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 the CLI itself said it had not applied it — Grok Build offering tools Browsentic never asks for, or Qwen Code reporting a denied tool or a second MCP server as registered. Update both, and report it |
+| `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 the CLI itself said it had not applied it — Grok Build offering tools Browsentic never asks for, Qwen Code reporting a denied tool or a second MCP server as registered, or OpenCode reporting that a tool outside the browser ran. Update both, and report it |
## Guardrails