Clawd Console
Your command deck
Clawdbot News & Articles • 2026-03-10 • One-Brain series (Part 1)

Two Brains Are Not Better Than One

If your Clawdbot sometimes works and sometimes doesn’t — duplicate replies, 502 after restart, “websocket disconnected”, or “the browser won’t start today” — you may not have a reliability problem. You may have a split brain.

This article explains the most common operator failure mode: split state across users/paths (often root vs master), plus duplicate services competing for the same ports and tokens. Then we show the migration pattern to the One-Brain standard.

Quick links

Part 2
One Brain, One Console
The practical runbook: systemd users, HOME, DATA_DIR, port cleanup, stable headless Chrome.

Why this happens

Agent deployments are unusually sensitive to “state location.” A normal web app can be stateless and scale. Clawdbot usually can’t — it has auth state, message state, browser state, and long-lived sessions.

  • Two users (root + non-root) ⇒ two different config/auth stores
  • Two services (or manual runs + service) ⇒ port collisions + race conditions
  • Two data dirs ⇒ transcript/PM/logs don’t match the process you’re debugging

Symptoms (what you see)

Split-brain is infamous because it looks like random flakiness. Common symptoms include:

  • Duplicate replies (two gateways/processes responding to the same inbound message)
  • 502 after restart (nginx points to a port that is now owned by a different process, or nothing)
  • “Clawdbot websocket disconnected” loops (console ↔ gateway or client ↔ console)
  • OAuth mismatch / “wrong account” behavior (the running process uses a different HOME/config than you expect)
  • Headless automation works until reboot, then fails (Chrome profile / permissions / locks are in the other user’s directory)
Operator signal
If “restart fixed it” is a common phrase in your incident notes, you’re probably restarting one brain while the other keeps running.

Root cause (split state: root vs master, duplicated services)

“Two brains” usually means you have two independent Clawdbot installations on the same machine — or two processes that behave like it — each with their own state.

The most common shape

  • You ran something manually as root during install/testing.
  • Later you created a service user (e.g. master) and ran systemd services there.
  • Now you have two sets of state:
    • /root/.clawdbot vs /home/master/.clawdbot (auth profiles/tokens/config)
    • two different DATA_DIR trees (PM/transcript/worklogs)
    • two processes competing for ports (gateway, console, browser debugging)
Key idea
Split-brain is not a bug. It’s a configuration topology.
If two “owners” can start/stop the system, you will see non-determinism at the operator level.

How to detect split-brain fast

You want to answer two questions: “Which process is running?” and “Which state is it using?”

1) Find duplicate listeners

ss -lntp
# Look for: two different PIDs holding the ports you expect
# or a port held by a process you didn’t intend to run.

2) Confirm the process owner (root vs master)

ps aux | egrep 'claw|node|gateway|console' | head

3) Confirm HOME/DATA_DIR at runtime

If you’re using systemd, inspect the unit file and ensure Environment=HOME=... and WorkingDirectory=... are explicit.

Image placeholder
(Insert: screenshot of two processes with different users, and ss showing duplicated listeners.)

Fix (One-Brain migration pattern)

The fix is not “kill the weird process and hope.” The fix is a controlled migration to a single canonical brain.

Step 1: Choose your canonical brain

  • Pick the service user that will own the system (commonly master).
  • Pick the canonical HOME and canonical DATA_DIR.

Step 2: Stop everything (cleanly)

Use systemd to stop the known services. Then confirm ports are free. Avoid starting anything manually while migrating.

systemctl stop clawdbot-gateway
systemctl stop clawdconsole
ss -lntp

Step 3: Consolidate state

Goal: one set of config/auth profiles and one data directory. If you have two, decide which to keep and migrate the needed pieces.

  • Auth/OAuth: ensure only one .clawdbot directory is used by services.
  • Data: ensure only one DATA_DIR is referenced in your service environment.

Step 4: Restart the canonical services

systemctl start clawdbot-gateway
systemctl start clawdconsole
Then follow the verification checklist in Part 2: One Brain, One Console.

Prevention (standard paths + services)

The goal is to make it impossible to accidentally start a second brain.

  • Run gateway/console as one dedicated service user only.
  • Set HOME + WorkingDirectory explicitly in systemd.
  • Put durable data in one DATA_DIR that is backed up/snapshotted.
  • Use a stable headless Chrome strategy (deb install + persistent user-data-dir + stable CDP port).
For symptom-first help, use the FAQ hub: Clawdbot User Guide, Install & Troubleshooting FAQs.

Get Early Access!

Launching any day…

Hosted Clawdbot + ClawdConsole workspaces are coming very, very soon.

Join the waitlist and we’ll spin up your workspace the moment access opens.

  • Same operator cockpit you’re seeing here
  • Private hosted workspace
  • We’ll email you your link when it’s ready
Back to the index: Clawdbot News & Articles