Remote Mode
Run the-brain on a Linux server, connect from macOS
Remote mode lets you run the-brain on a headless Linux server while using your Mac as a client.
Architecture
┌─ Linux Server ──────────────────────┐
│ the-brain daemon start │
│ ├─ API :9420 ← Bearer mb_xxx │
│ ├─ MCP SSE :9422 ← Bearer mb_xxx │
│ └─ Storage: SQLite or LibSQL │
└─────────────────────────────────────┘
▲ ▲
│ │
┌────┴──────┐ ┌────┴──────────┐
│ Agent │ │ MCP Client │
│ (Mac) │ │ │
│ Cursor │ │ Claude Desktop│
│ Claude CD │ │ Cursor, Zed │
│ Windsurf │ │ │
│ → push 60s│ │ → SSE + auth │
└───────────┘ └───────────────┘Server Setup
# On Linux server
the-brain init --remote
# → Generates auth token, sets bindAddress: 0.0.0.0
the-brain daemon start
# → API on 0.0.0.0:9420, MCP SSE on 0.0.0.0:9422
cat ~/.the-brain/config.json | grep authToken
# → Save this token!Client Setup
# On macOS
export THE_BRAIN_REMOTE_URL="http://<server-ip>:9420"
export THE_BRAIN_AUTH_TOKEN="mb_<token>"
# Start push agent (polls local IDE logs, pushes to server)
the-brain agent
# Or one-shot
the-brain agent --onceAuth
All endpoints except /api/health require:
Authorization: Bearer mb_<token>The agent automatically adds this header.
Storage Options
- SQLite (default): Local to server
- LibSQL (Turso): Shared across multiple servers
the-brain backend set --slot storage --backend libsql