delphi-broker

Approval-gated MCP message broker for routing communication between CLI agents across Tailscale-connected hosts.

Replaces manual copy-paste routing in a Delphi-method workflow where multiple independent agents (Codex, Claude Code) develop solutions across separate hosts and a human orchestrator synthesizes results via a phone-friendly web UI.

• FastAPI application with three surfaces:
• /api/v1/ — REST API
• /mcp — MCP (Model Context Protocol) server for Claude Code integration
• /web/ — Phone-friendly approval interface
• SQLite (WAL mode) for message and agent state
• Message lifecycle: PENDING -> APPROVED/REJECTED -> ACKED
• Role-based access: orchestrator role required for approve/reject/broadcast

Infrastructure config lives in .env (copy from .env.example):

DELPHI_HOST=0.0.0.0
DELPHI_PORT=8420
DELPHI_DB_PATH=delphi.db

Agent registry lives in config/agents.json (gitignored, copy from example):

cp config/agents.json.example config/agents.json  # then edit with your agents

{
  "agents": [
    {"agent_id": "host1-codex", "host": "host1", "roles": "worker"},
    {"agent_id": "host2-claude", "host": "host2", "roles": "worker,orchestrator"}
  ]
}

cp .env.example .env  # adjust as needed
docker compose -p delphi-broker up -d --build

> ⚠️ The -p delphi-broker flag isolates this stack from other compose projects (e.g., LexxAI) on the same host.

Data persists in ./data/ (SQLite DB). Agent registry is mounted read-only from ./config/.

pip install -r requirements.txt
cp .env.example .env  # adjust as needed
python -m uvicorn delphi_broker.main:app --host 0.0.0.0 --port 8420 --app-dir src

Add to ~/.claude/settings.json on each agent host:

{
  "mcpServers": {
    "delphi-broker": {
      "type": "url",