Document host browser debugging setup
Add Browser Settings guidance for supported Chromium-family remote debugging pages, including Opera and explicit remote-debugging endpoint fallback. Update BYOB docs and troubleshooting to clarify that browser inventory comes from the connected A0 CLI and requires reconnecting the CLI after authorizing a browser.
Alessandro committed
Jul 5, 2026 at 18:59 UTC
c71913453711a370deb9b044a2e61d99c6764a59
6 files changed
+71
-10
README.md
+1
-1
@@ -121,7 +121,7 @@ Annotate mode turns any webpage into an interactive directive surface. Click an
121
- **Lift it** - see a card, hero, or component on someone else's site that you like? Capture it and have the agent re-implement it in your own project's stack.
122
- **Comment it** - leave actionable notes pinned to elements during a UI review; the agent reads the comments and ships the fixes.
123
124
-The Docker browser is the default live Browser surface. Browser history keeps screenshots of important steps, so older chats can still show what the agent saw. The Browser also supports Chrome extensions inside the Docker browser, and **Bring Your Own Browser** through the A0 CLI Connector lets the agent drive Chrome/Edge/Chromium on your own machine.
124
+The Docker browser is the default live Browser surface. Browser history keeps screenshots of important steps, so older chats can still show what the agent saw. The Browser also supports Chrome extensions inside the Docker browser, and **Bring Your Own Browser** through the A0 CLI Connector lets the agent drive Chrome, Edge, Brave, Opera, Vivaldi, or Chromium on your own machine.
125
126
See the [Browser guide](./docs/guides/browser.md) for screenshots, settings, host-browser setup, and troubleshooting.
127
docs/guides/a0-cli-connector.md
+29
-5
@@ -132,15 +132,22 @@ machine.
132
- [ ] Keep A0 CLI connected to the Agent Zero chat.
133
- [ ] In Agent Zero Web UI, open Browser plugin settings and choose **Bring Your
134
Own Browser**.
135
-- [ ] If you want Agent Zero to use an already-open personal Chrome window, open
136
- that browser first.
137
-- [ ] In that browser, go to `chrome://inspect/#remote-debugging`.
135
+- [ ] If you want Agent Zero to use an already-open personal browser window,
136
+ open that browser first.
137
+- [ ] In that browser, open its remote debugging page.
138
- [ ] Enable **Allow remote debugging for this browser instance**.
139
140
+Remote debugging pages:
141
+
142
+| Browser | Page |
143
+| --- | --- |
144
+| Chrome, Edge, Brave, Vivaldi, Chromium | `chrome://inspect/#remote-debugging` |
145
+| Opera | `opera://inspect/#remote-debugging` |
146
+
147
148
149
When Agent Zero performs its first Browser action against that host browser,
143
-Chrome asks for confirmation. Click **Allow** if you trust this Agent Zero
150
+the browser asks for confirmation. Click **Allow** if you trust this Agent Zero
151
instance and A0 CLI connection.
152
153
@@ -149,11 +156,28 @@ A0 CLI does not take over the browser while it is only checking status. Browser
156
control starts when Agent Zero actually needs to use the browser.
157
158
> [!IMPORTANT]
152
-> Remote debugging gives the connected app full control of that Chrome session,
159
+> Remote debugging gives the connected app full control of that browser session,
160
> including access to saved data, cookies, site data, and navigation. Use it only
161
> with trusted Agent Zero instances and browser windows you intend the agent to
162
> control.
163
164
+The **Host browser** list in Browser settings comes from the connected local A0
165
+CLI, not from the Agent Zero Web UI server. If a newly authorized browser does
166
+not appear, restart or reconnect A0 CLI.
167
+
168
+If the inspect checkbox is not enough for your browser build, launch it with an
169
+explicit remote debugging port and a separate profile:
170
+
171
+```bash
172
+opera --remote-debugging-port=9222 --user-data-dir="$HOME/.config/a0-opera-debug"
173
+```
174
+
175
+Then pass the full DevTools websocket endpoint to A0 CLI:
176
+
177
+```bash
178
+export A0_HOST_BROWSER_REMOTE_DEBUGGING_ENDPOINTS="ws://127.0.0.1:9222/devtools/browser/..."
179
+```
180
+
181
### Browser Profiles
182
183
```bash
docs/guides/browser.md
+29
-4
@@ -137,8 +137,8 @@ development, Agent Zero can install it the first time it is needed.
137
138
## Bring Your Own Browser
139
140
-Bring Your Own Browser lets Agent Zero use Chrome, Edge, or Chromium on your own
141
-computer through A0 CLI.
140
+Bring Your Own Browser lets Agent Zero use Chrome, Edge, Brave, Opera, Vivaldi,
141
+or Chromium on your own computer through A0 CLI.
142
143
Use it when the page, login, or browser profile should stay on your machine.
144
@@ -146,8 +146,33 @@ Requirements:
146
147
- [ ] Keep A0 CLI connected to the Agent Zero chat.
148
- [ ] Choose **Bring Your Own Browser** in Browser settings.
149
-- [ ] Use Chrome, Edge, or Chromium on the host.
150
-- [ ] For personal Chrome remote debugging, open the host browser first, go to `chrome://inspect/#remote-debugging`, and enable **Allow remote debugging for this browser instance**.
149
+- [ ] Use a Chromium-family browser on the host: Chrome, Edge, Brave, Opera, Vivaldi, or Chromium.
150
+- [ ] For an already-open browser, open its remote debugging page and enable **Allow remote debugging for this browser instance**.
151
+
152
+Remote debugging pages:
153
+
154
+| Browser | Page |
155
+| --- | --- |
156
+| Chrome, Edge, Brave, Vivaldi, Chromium | `chrome://inspect/#remote-debugging` |
157
+| Opera | `opera://inspect/#remote-debugging` |
158
+
159
+If a browser does not appear in the **Host browser** list after enabling remote
160
+debugging, restart or reconnect the local A0 CLI. Restarting only the Agent Zero
161
+Web UI server does not refresh the browser inventory; the list comes from the
162
+connected CLI.
163
+
164
+As a fallback, launch the browser with an explicit debugging port and profile
165
+directory:
166
+
167
+```bash
168
+opera --remote-debugging-port=9222 --user-data-dir="$HOME/.config/a0-opera-debug"
169
+```
170
+
171
+Then pass the full DevTools websocket endpoint to the CLI:
172
+
173
+```bash
174
+export A0_HOST_BROWSER_REMOTE_DEBUGGING_ENDPOINTS="ws://127.0.0.1:9222/devtools/browser/..."
175
+```
176
177
178
docs/guides/troubleshooting.md
+1
@@ -41,6 +41,7 @@ PLAYWRIGHT_BROWSERS_PATH=tmp/playwright playwright install chromium
41
If **Bring Your Own Browser** mode fails:
42
43
- keep A0 CLI connected to the chat;
44
+- restart or reconnect A0 CLI after enabling remote debugging in a browser;
45
- run `/browser status` in A0 CLI;
46
- check that Browser settings still say **Bring Your Own Browser**;
47
- check **Page content access** if page text or screenshots are blocked.
plugins/_browser/webui/config.html
+10
@@ -82,6 +82,16 @@
82
<span class="browser-config-field-help">Choose which installed browser/debug endpoint A0 CLI should use when multiple are available.</span>
83
</label>
84
85
+ <div
86
+ class="browser-config-note"
87
+ x-show="$store.browserConfig.config.runtime_backend === 'host_required' && $store.browserConfig.config.host_browser_profile_mode !== 'agent'"
88
+ >
89
+ <span class="material-symbols-outlined">info</span>
90
+ <span>
91
+ For an already-open browser, Chrome, Edge, Brave, Vivaldi, and Chromium use chrome://inspect/#remote-debugging; Opera uses opera://inspect/#remote-debugging. Enable "Allow remote debugging for this browser instance", then restart or reconnect A0 CLI if the browser does not appear. If needed, launch the browser with --remote-debugging-port=9222 and --user-data-dir=<profile-dir>, or set A0_HOST_BROWSER_REMOTE_DEBUGGING_ENDPOINTS to the full ws://.../devtools/browser/... endpoint.
92
+ </span>
93
+ </div>
94
+
95
<div
96
class="browser-config-warning"
97
x-show="$store.browserConfig.config.runtime_backend === 'host_required' && $store.browserConfig.config.host_browser_profile_mode !== 'agent'"
tests/test_browser_agent_regressions.py
+1
@@ -1001,6 +1001,7 @@ def test_browser_tool_does_not_auto_open_canvas_policy_is_documented():
1001
assert "already-open Browser surface" in config_html
1002
assert "chrome://inspect/#remote-debugging" in config_html
1003
assert "opera://inspect/#remote-debugging" in config_html
1004
+ assert "A0_HOST_BROWSER_REMOTE_DEBUGGING_ENDPOINTS" in config_html
1005
1006
1007
def test_browser_skills_are_plugin_owned_and_progressively_linked():