From fe46a2663bfab997e1da9ffbfe1379110c80c326 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 11 Jan 2026 01:55:38 +0100
Subject: [PATCH] docs: clarify browser allowlist defaults and risks

---
 docs/gateway/configuration.md | 1 +
 docs/gateway/security.md      | 9 +++++++++
 docs/tools/browser.md         | 1 +
 3 files changed, 11 insertions(+)

diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index e88b70926..165ef74cb 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -1471,6 +1471,7 @@ Allowlists for remote control:
 - `allowedControlUrls`: exact control URLs permitted for `target: "custom"`.
 - `allowedControlHosts`: hostnames permitted (hostname only, no port).
 - `allowedControlPorts`: ports permitted (defaults: http=80, https=443).
+Defaults: all allowlists are unset (no restriction). `allowHostControl` defaults to false.
 
 ### `models` (custom providers + base URLs)
 
diff --git a/docs/gateway/security.md b/docs/gateway/security.md
index ec5813fac..25b3bf8e2 100644
--- a/docs/gateway/security.md
+++ b/docs/gateway/security.md
@@ -199,6 +199,15 @@ Also consider agent workspace access inside the sandbox:
 
 Important: `tools.elevated` is the global baseline escape hatch that runs bash on the host. Keep `tools.elevated.allowFrom` tight and don’t enable it for strangers. You can further restrict elevated per agent via `agents.list[].tools.elevated`. See [Elevated Mode](/tools/elevated).
 
+## Browser control risks
+
+Enabling browser control gives the model the ability to drive a real browser.
+If that browser profile already contains logged-in sessions, the model can
+access those accounts and data. Treat browser profiles as **sensitive state**:
+- Prefer a dedicated profile for the agent (the default `clawd` profile).
+- Avoid pointing the agent at your personal daily-driver profile.
+- Keep host browser control disabled for sandboxed agents unless you trust them.
+
 ## Per-agent access profiles (multi-agent)
 
 With multi-agent routing, each agent can have its own sandbox + tool policy:
diff --git a/docs/tools/browser.md b/docs/tools/browser.md
index 8dfe11961..5684d4522 100644
--- a/docs/tools/browser.md
+++ b/docs/tools/browser.md
@@ -245,5 +245,6 @@ How it maps:
   - In sandboxed sessions, `target: "host"` requires `agents.defaults.sandbox.browser.allowHostControl=true`.
   - If `target` is omitted: sandboxed sessions default to `sandbox`, non-sandbox sessions default to `host`.
   - Sandbox allowlists can restrict `target: "custom"` to specific URLs/hosts/ports.
+  - Defaults: allowlists unset (no restriction), and sandbox host control is disabled.
 
 This keeps the agent deterministic and avoids brittle selectors.