From 27a77454ae54e60023849dc44ab7a35f53a30e79 Mon Sep 17 00:00:00 2001
From: Julian Engel <julian@codeero.com>
Date: Mon, 5 Jan 2026 15:00:49 +0000
Subject: [PATCH] docs: add Linux browser troubleshooting guide

Covers:
- Snap Chromium issues on Ubuntu
- Solution 1: Install Google Chrome (recommended)
- Solution 2: attachOnly mode workaround
- Systemd service for auto-starting browser
- Config reference
---
 docs/browser-linux-troubleshooting.md | 109 ++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 docs/browser-linux-troubleshooting.md

diff --git a/docs/browser-linux-troubleshooting.md b/docs/browser-linux-troubleshooting.md
new file mode 100644
index 000000000..33643634a
--- /dev/null
+++ b/docs/browser-linux-troubleshooting.md
@@ -0,0 +1,109 @@
+# Browser Troubleshooting (Linux)
+
+## Problem: "Failed to start Chrome CDP on port 18800"
+
+Clawdbot's browser control server fails to launch Chrome/Chromium with the error:
+```
+{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"clawd\"."}
+```
+
+### Root Cause
+
+On Ubuntu (and many Linux distros), the default Chromium installation is a **snap package**. Snap's AppArmor confinement interferes with how Clawdbot spawns and monitors the browser process.
+
+The `apt install chromium` command installs a stub package that redirects to snap:
+```
+Note, selecting 'chromium-browser' instead of 'chromium'
+chromium-browser is already the newest version (2:1snap1-0ubuntu2).
+```
+
+This is NOT a real browser — it's just a wrapper.
+
+### Solution 1: Install Google Chrome (Recommended)
+
+Install the official Google Chrome `.deb` package, which is not sandboxed by snap:
+
+```bash
+wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+sudo dpkg -i google-chrome-stable_current_amd64.deb
+sudo apt --fix-broken install -y  # if there are dependency errors
+```
+
+Then update your Clawdbot config (`~/.clawdbot/clawdbot.json`):
+
+```json
+{
+  "browser": {
+    "enabled": true,
+    "executablePath": "/usr/bin/google-chrome-stable",
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+### Solution 2: Use Snap Chromium with Attach-Only Mode
+
+If you must use snap Chromium, configure Clawdbot to attach to a manually-started browser:
+
+1. Update config:
+```json
+{
+  "browser": {
+    "enabled": true,
+    "attachOnly": true,
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+2. Start Chromium manually:
+```bash
+chromium-browser --headless --no-sandbox --disable-gpu \
+  --remote-debugging-port=18800 \
+  --user-data-dir=$HOME/.clawdbot/browser/clawd/user-data \
+  about:blank &
+```
+
+3. Optionally create a systemd user service to auto-start Chrome:
+```ini
+# ~/.config/systemd/user/clawd-browser.service
+[Unit]
+Description=Clawd Browser (Chrome CDP)
+After=network.target
+
+[Service]
+ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.clawdbot/browser/clawd/user-data about:blank
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Enable with: `systemctl --user enable --now clawd-browser.service`
+
+### Verifying the Browser Works
+
+Check status:
+```bash
+curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'
+```
+
+Test browsing:
+```bash
+curl -s -X POST http://127.0.0.1:18791/start
+curl -s http://127.0.0.1:18791/tabs
+```
+
+### Config Reference
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `browser.enabled` | Enable browser control | `true` |
+| `browser.executablePath` | Path to Chrome/Chromium binary | auto-detected |
+| `browser.headless` | Run without GUI | `false` |
+| `browser.noSandbox` | Add `--no-sandbox` flag (needed for some Linux setups) | `false` |
+| `browser.attachOnly` | Don't launch browser, only attach to existing | `false` |
+| `browser.cdpPort` | Chrome DevTools Protocol port | `18800` |