Skip to main content

​
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. Install the official Google Chrome .deb package, which is not sandboxed by snap: 
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): 
{
  "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:
{
  "browser": {
    "enabled": true,
    "attachOnly": true,
    "headless": true,
    "noSandbox": true
  }
}
  1. Start Chromium manually:
chromium-browser --headless --no-sandbox --disable-gpu \
  --remote-debugging-port=18800 \
  --user-data-dir=$HOME/.clawdbot/browser/clawd/user-data \
  about:blank &
  1. Optionally create a systemd user service to auto-start Chrome:
# ~/.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: 
curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'
Test browsing: 
curl -s -X POST http://127.0.0.1:18791/start
curl -s http://127.0.0.1:18791/tabs

​
Config Reference

OptionDescriptionDefault
browser.enabledEnable browser controltrue
browser.executablePathPath to Chrome/Chromium binaryauto-detected
browser.headlessRun without GUIfalse
browser.noSandboxAdd --no-sandbox flag (needed for some Linux setups)false
browser.attachOnlyDon’t launch browser, only attach to existingfalse
browser.cdpPortChrome DevTools Protocol port18800