From 2d066b8715dd233c4f90f7ba89acf161dfabef91 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 15 Jan 2026 05:17:12 +0000
Subject: [PATCH] docs: explain sandboxed browser control

---
 docs/tools/browser.md          |  7 +++++++
 docs/tools/chrome-extension.md | 29 +++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/docs/tools/browser.md b/docs/tools/browser.md
index dd7b0e45b..7bb9dc79b 100644
--- a/docs/tools/browser.md
+++ b/docs/tools/browser.md
@@ -224,6 +224,13 @@ Flow:
 If the Gateway runs on the same machine as Chrome (default setup), you usually **do not** need `clawdbot browser serve`.
 Use `browser serve` only when the Gateway runs elsewhere (remote mode).
 
+### Sandboxed sessions
+
+If the agent session is sandboxed, the `browser` tool may default to `target="sandbox"` (sandbox browser).
+Chrome extension relay takeover requires host browser control, so either:
+- run the session unsandboxed, or
+- set `agents.defaults.sandbox.browser.allowHostControl: true` and use `target="host"` when calling the tool.
+
 ### Setup
 
 1) Create a profile that uses the extension driver:
diff --git a/docs/tools/chrome-extension.md b/docs/tools/chrome-extension.md
index fb787390a..6eb5a7dc2 100644
--- a/docs/tools/chrome-extension.md
+++ b/docs/tools/chrome-extension.md
@@ -85,6 +85,35 @@ auto-start the local relay server when you use a profile with `driver="extension
 If your Gateway runs on another machine, run `clawdbot browser serve` on the machine that runs Chrome
 (and publish it via Tailscale Serve / TLS). See the section below.
 
+## Sandboxing (tool containers)
+
+If your agent session is sandboxed (`agents.defaults.sandbox.mode != "off"`), the `browser` tool can be restricted:
+
+- By default, sandboxed sessions often target the **sandbox browser** (`target="sandbox"`), not your host Chrome.
+- Chrome extension relay takeover requires controlling the **host** browser control server.
+
+Options:
+- Easiest: use the extension from a **non-sandboxed** session/agent.
+- Or allow host browser control for sandboxed sessions:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        browser: {
+          allowHostControl: true
+        }
+      }
+    }
+  }
+}
+```
+
+Then ensure the tool isn’t denied by tool policy, and (if needed) call `browser` with `target="host"`.
+
+Debugging: `clawdbot sandbox explain`
+
 ## Remote Gateway (recommended: Tailscale Serve)
 
 Goal: Gateway runs on one machine, but Chrome runs somewhere else.