One Brain, One Console

The standard (what “One Brain” means)

“One Brain” means: exactly one canonical place where your Clawdbot state lives, and exactly one canonical service identity that owns it.

• One service user runs the gateway/console (don’t mix root + another user).
• One HOME (so auth tokens, cookies, and tool caches don’t split).
• One DATA_DIR (so transcript/PM/worklogs are not duplicated).
• One set of ports (so restarts don’t leave orphan processes holding the old ports).

The runbook (systemd + paths + ports)

Here’s the shape of a known-good layout. Adapt the exact paths/ports to your environment, but keep the intent: one user, one home, one data directory, and one place to restart.

1) Pick the service user (and stick to it)

If you already have a “working” install, the goal is to consolidate — not to create a parallel second install.

2) Make HOME + WorkingDirectory explicit in systemd

Don’t rely on defaults. Defaults change (and differ between manual runs vs services).

[Service]
User=master
Group=master
WorkingDirectory=/home/master/clawd
Environment=HOME=/home/master

# Example: console service (adjust as needed)
ExecStart=/usr/bin/node /home/master/clawd/apps/console/server.js
Restart=on-failure
RestartSec=2

3) Put persistent data in DATA_DIR

Your console should read/write append-only or durable data (PM board, transcript, worklog) in one directory that survives upgrades.

# Example
DATA_DIR=/home/master/clawd/apps/console-data

4) Port cleanup: eliminate collisions

A common failure mode is: you restart “the” service but an old process still holds the port. The symptom becomes 502s, websockets flapping, or browser control failing to connect.

# See what’s listening (example)
ss -lntp

# If needed, use systemd to restart the canonical service
# (avoid ad-hoc node runs that create a second brain)
systemctl restart clawdbot-gateway
systemctl restart clawdconsole

Browser automation stability (headless Chrome)

For operator-grade reliability, treat the browser as a long-lived dependency, not a disposable spawn. The two big levers:

• Use a real Chrome build (deb install) when possible (fewer sandbox/snap oddities).
• Use a persistent user-data-dir so logins/cookies survive restarts (this is “persistent session”).

Known-good pattern: remote-debugging + persistent profile

Start Chrome with a stable debugging port and a stable profile directory. Then verify it’s reachable via the DevTools endpoint.

# Example (adjust paths)
google-chrome \
  --headless=new \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=18800 \
  --user-data-dir=/home/master/clawd/apps/console-data/chrome-profile

Quick verification: /json/version

curl -s http://127.0.0.1:18800/json/version

Verification checklist (10 minutes)

1. One user: confirm the gateway/console processes run as the same OS user.
2. One HOME: confirm systemd sets HOME explicitly (and it matches where your auth profiles live).
3. DATA_DIR exists: confirm your durable data writes to one directory you can back up.
4. Ports: confirm the expected ports are listening, and only one process owns each.
5. Websocket sanity: confirm the gateway/console connection is stable (no constant reconnect loop).
6. Browser control: confirm Chrome DevTools endpoint returns /json/version and the automation client can connect.

Troubleshooting (FAQ deep dives)

If you’re already firefighting, these pages are designed to be symptom-first:

• Clawdbot gateway
• Clawdbot websocket disconnected
• Clawdbot headless Chrome
• Clawdbot persistent session
• Clawdbot debugging (remote debugging / CDP)
• Clawdbot troubleshooting (overview)