From 612cdac4c32f0770790f0453756647bae3d48f51 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 15 Jan 2026 05:15:33 +0000
Subject: [PATCH] docs: clarify when browser serve is needed

---
 docs/start/faq.md              |  2 ++
 docs/tools/browser.md          |  3 +++
 docs/tools/chrome-extension.md | 15 +++++++++++++++
 3 files changed, 20 insertions(+)

diff --git a/docs/start/faq.md b/docs/start/faq.md
index 27d2c68e2..cbffaba0d 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -413,6 +413,8 @@ Then Chrome → `chrome://extensions` → enable “Developer mode” → “Loa
 
 Full guide (including remote Gateway via Tailscale + security notes): [Chrome extension](/tools/chrome-extension)
 
+If the Gateway runs on the same machine as Chrome (default setup), you usually **do not** need `clawdbot browser serve`.
+
 ## Sandboxing and memory
 
 ### Is there a dedicated sandboxing doc?
diff --git a/docs/tools/browser.md b/docs/tools/browser.md
index 92a5950ec..dd7b0e45b 100644
--- a/docs/tools/browser.md
+++ b/docs/tools/browser.md
@@ -221,6 +221,9 @@ Flow:
 - You click the **Clawdbot Browser Relay** extension icon on a tab to attach.
 - The agent controls that tab via the normal `browser` tool, by selecting the right profile.
 
+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).
+
 ### 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 67054400e..fb787390a 100644
--- a/docs/tools/chrome-extension.md
+++ b/docs/tools/chrome-extension.md
@@ -70,6 +70,21 @@ Then target it:
   - Badge shows `ON` when attached.
 - Click again to detach.
 
+## Do I need `clawdbot browser serve`?
+
+### Local Gateway (same machine as Chrome) — usually **no**
+
+If the Gateway is running on the same machine as Chrome and your `browser.controlUrl` is loopback (default),
+you typically **do not** need `clawdbot browser serve`.
+
+The Gateway’s built-in browser control server will start on `http://127.0.0.1:18791/` and Clawdbot will
+auto-start the local relay server when you use a profile with `driver="extension"`.
+
+### Remote Gateway (Gateway runs elsewhere) — **yes**
+
+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.
+
 ## Remote Gateway (recommended: Tailscale Serve)
 
 Goal: Gateway runs on one machine, but Chrome runs somewhere else.