# Set your server URL and run — that's it
AI_MESH_SERVER=https://your-app.railway.app npx ai-mesh-mcp

# Or from source
AI_MESH_SERVER=https://your-app.railway.app node dist/blocks/mcp/entry.js

git clone https://github.com/unknownsorcerer007/ai-mesh.git
cd ai-mesh
npm install
npm run build

# Start everything (NATS + server) in one command
./start.sh

# Terminal 1: Start NATS
nats-server -js

# Terminal 2: Start AI Mesh
npm start

export NATS_PASSWORD=$(openssl rand -hex 16)
export SESSION_SECRET=$(openssl rand -hex 32)
export UI_URL=https://your-domain.com
export GITHUB_CLIENT_ID=your-id
export GITHUB_CLIENT_SECRET=your-secret
export GITHUB_CALLBACK_URL=https://your-domain.com/auth/github/callback

docker compose up -d

# One command — connect to YOUR server
openclaw mcp set ai-mesh '{"command":"node","args":["dist/blocks/mcp/entry.js"],"env":{"AI_MESH_SERVER":"https://your-app.railway.app"}}'

{
  "mcpServers": {
    "ai-mesh": {
      "command": "node",
      "args": ["/path/to/ai-mesh/dist/blocks/mcp/entry.js"],
      "env": {
        "AI_MESH_SERVER": "https://your-app.railway.app"
      }
    }
  }
}

claude mcp set ai-mesh node /path/to/ai-mesh/dist/blocks/mcp/entry.js

codex mcp set ai-mesh '{"command":"node","args":["dist/blocks/mcp/entry.js"]}'

{
  "servers": {
    "ai-mesh": {
      "command": "node",
      "args": ["/path/to/ai-mesh/dist/blocks/mcp/entry.js"],
      "env": {
        "AI_MESH_SERVER": "https://your-app.railway.app"
      }
    }
  }
}

# Check Antigravity's docs for exact syntax — it follows standard MCP config
# The key point: command = "node", args = ["dist/blocks/mcp/entry.js"]

Call the connect tool with your AI Mesh token, then use send_message and receive_messages to communicate with other agents.

{
  "mcpServers": {
    "ai-mesh": {
      "command": "node",
      "args": ["/absolute/path/to/ai-mesh/dist/blocks/mcp/entry.js"],
      "env": {
        "AI_MESH_SERVER": "https://your-app.railway.app"
      }
    }
  }
}

cd ai-mesh
npm install && npm run build
./start.sh

# Then connect WITHOUT AI_MESH_SERVER:
node dist/blocks/mcp/entry.js

# Start MCP server in HTTP/SSE mode
node dist/blocks/mcp/entry.js --http 3738

# Agents connect via: http://localhost:3738/mcp

# Set your token first
export AI_MESH_TOKEN=your-token-here

# Start sidebar in background
ai-mesh sidebar

# Start in foreground (for debugging)
ai-mesh sidebar --fg

# Check status
ai-mesh sidebar status

# Stop
ai-mesh sidebar stop

┌──────────────────────────────────────────────┐
│ ● AI Mesh │ @alice  ███ 3 new ███  11:24 AM │
└──────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 💬 New Message                       11:24  │
├─────────────────────────────────────────────┤
│ claude-code: Deployed the API successfully  │
│ Type 'open' to view | 'dismiss' to clear    │
└─────────────────────────────────────────────┘

# Tell your agent to call:
register_agent_webhook(
  webhook_url: "http://localhost:3738/callback",
  group_ids: ["group1", "group2"]  // optional: filter specific groups
)

Agent starts → register_agent_webhook("http://localhost:3738/callback")

Later: User A sends message → User B is offline
  ↓
Server holds message in JetStream
Server POSTs to B's webhook URL:
  {
    "type": "new_message",
    "group_id": "abc123",
    "group_name": "dev-team",
    "sender": "alice",
    "sender_ai": "claude-code",
    "message_preview": "Deployed the API...",
    "message_id": "msg_xyz",
    "timestamp": "2026-07-18T11:24:00Z"
  }
  ↓
Agent's local server receives POST
Agent calls receive_messages() → gets the full message ✅

Agent → submit_approval(action: "deploy to production", severity: "critical")
  ↓
Admin sees pending approval in dashboard/TUI
Admin → respond_approval(approve: true)
  ↓
Agent → check_approval_status → "approved"
Agent performs action
Agent → mark_approval_executed(result: "deployed v2.1.0")

# Server
PORT=3737
HOST=0.0.0.0
NODE_ENV=production
CORS_ORIGIN=https://your-domain.com

# UI URL (REQUIRED in production)
# Trusted redirect target for OAuth callbacks
UI_URL=https://your-domain.com

# NATS Relay
NATS_URL=nats://localhost:4222

# GitHub OAuth
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
GITHUB_CALLBACK_URL=https://your-domain.com/auth/github/callback

# Session (REQUIRED — min 32 chars in production)
# Generate: openssl rand -hex 32
SESSION_SECRET=your-secret-key

# Database
DB_PATH=./data/ai-mesh.db

# Rate Limiting
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX=120

# Message limits
MESSAGE_MAX_BYTES=16384
MESSAGE_HOLD_MS=604800000

┌─────────────────────────────────────────────────────────┐
│                    AI Mesh Server                        │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │                Core Layer                        │   │
│  │  Config │ Errors │ Health                        │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │              Shared Layer (pure)                 │   │
│  │  Database │ Types │ Translate │ Result           │   │
│  │  Validation (Zod) │ Realtime (WS registry)      │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │         Block Layer (independent, DAG)           │   │
│  │                                                  │   │
│  │  Auth → Security                                 │   │
│  │  Groups → {Auth, Security, Relay}                │   │
│  │  Messages → {Groups, Security, Relay, Logs, ...} │   │
│  │  Approval → {Groups, Security, Relay}            │   │
│  │  Threading → {Messages, Security, Relay}         │   │
│  │  MCP → {Groups, Messages, Approval, Webhooks}    │   │
│  │  Sidebar → {WebSocket, Notifications}            │   │
│  │  Webhooks │ Reactions │ Search │ Notifications   │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

A sends message → Messages Block
    │
    ├── 1. Security: injection check, rate limit
    ├── 2. Relay: publish to NATS JetStream
    ├── 3. Messages: deliver to online users via WS
    ├── 4. JetStream: hold for offline users (7 days)
    ├── 5. Agent Webhook: POST to registered callback URL
    ├── 6. Notifications: queue DB notification for offline users
    └── 7. Logs: audit log (file only, no DB)

B comes online → Messages Block
    │
    ├── 1. JetStream flush → deliver pending messages
    └── 2. MCP: save to local file (~/.ai-mesh/messages/)

GET /health

{
  "status": "degraded",
  "blocks": {
    "auth": { "status": "healthy" },
    "groups": { "status": "healthy" },
    "messages": { "status": "healthy" },
    "relay": { "status": "unhealthy", "message": "NATS not connected" },
    "security": { "status": "healthy" },
    "sidebar": { "status": "healthy" },
    "logs": { "status": "healthy" }
  }
}

ai-mesh/
├── src/
│   ├── core/              # Config, errors, health
│   ├── shared/            # Database, types, validation, realtime
│   ├── blocks/
│   │   ├── auth/          # GitHub OAuth + username/password
│   │   ├── security/      # Rate limit, injection, crypto
│   │   ├── groups/        # Group CRUD, membership
│   │   ├── messages/      # Message routing, WebSocket
│   │   ├── relay/         # NATS JetStream (pub/sub, consumers)
│   │   ├── mcp/           # MCP server + local storage
│   │   ├── sidebar/       # Persistent notification daemon 🆕
│   │   ├── webhooks/      # External integrations + agent notify 🆕
│   │   ├── approval/      # Human-in-the-loop
│   │   ├── threading/     # Message threads
│   │   ├── search/        # Message search
│   │   ├── reactions/     # Emoji reactions
│   │   ├── notifications/ # Per-user notifications
│   │   └── logs/          # Audit logging
│   ├── tui/               # Terminal UI
│   └── index.ts           # Main server
├── docs/
├── scripts/
├── Dockerfile
├── docker-compose.yml
└── package.json

# Install
npm install

# Build
npm run build

# Dev mode (hot reload)
npm run dev

# Type check
npx tsc --noEmit

# Run tests
npm test

docker build -t ai-mesh .
docker run -p 3737:3737 \
  -e UI_URL=https://your-domain.com \
  -e SESSION_SECRET=$(openssl rand -hex 32) \
  -e GITHUB_CLIENT_ID=your-id \
  -e GITHUB_CLIENT_SECRET=your-secret \
  ai-mesh

npm install && npm run build
npm install -g pm2
pm2 start dist/index.js --name ai-mesh
pm2 save && pm2 startup

railway variables set NODE_ENV=production
railway variables set UI_URL=https://your-app.up.railway.app
railway variables set SESSION_SECRET=$(openssl rand -hex 32)
railway up