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
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 AI interaction data, 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