# Clone the repository
git clone https://github.com/candordotcodes/candor.git
cd candor
# Install dependencies
npm install
# Set up the database
npx prisma migrate dev
# Start the dev server
npm run dev
# Open dashboard at http://localhost:3000

# Clone the repository
git clone https://github.com/candordotcodes/candor.git
cd candor
# Install dependencies
npm install
# Set up environment
cp .env.example .env
# Edit .env with your DATABASE_URL and JWT_SECRET

# Start the development server
npm run dev
# Dashboard available at http://localhost:3000
# Proxy available at http://localhost:3100

1{
2  "proxy": {
3    "port": 3100,
4    "dashboard": 3200,
5    "websocket": 3101
6  },
7  "upstreams": [
8    {
9      "name": "filesystem",
10      "transport": "stdio",
11      "command": "npx",
12      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
13    },
14    {
15      "name": "github",
16      "transport": "sse",
17      "url": "https://mcp.github.com/sse"
18    }
19  ],
20  "storage": {
21    "driver": "postgres",
22    "url": "postgresql://user:pass@localhost:5432/candor"
23  },
24  "retention": {
25    "days": 7,
26    "maxEventsPerSession": 1000
27  }
28}

1// Claude Desktop: ~/.claude/claude_desktop_config.json
2// Before (direct connection):
3{
4  "mcpServers": {
5    "filesystem": {
6      "command": "npx",
7      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
8    }
9  }
10}
11
12// After (through Candor proxy):
13{
14  "mcpServers": {
15    "candor-proxy": {
16      "command": "candor",
17      "args": ["start", "--attach"]
18    }
19  }
20}

candor start [options]
Options:
  --port <number>       Proxy port (default: 3100)
  --dashboard <number>  Dashboard port (default: 3200)
  --config <path>       Path to config file (default: ./candor.config.json)
  --no-dashboard        Start proxy only, skip dashboard
  --attach              Run in attached mode (for MCP client integration)
  --verbose             Enable verbose logging
Examples:
  candor start
  candor start --port 4100 --dashboard 4200
  candor start --no-dashboard
  candor start --config ./custom-config.json

candor init [options]
Options:
  --dir <path>     Output directory (default: current directory)
  --template <id>  Use a starter template (basic, advanced)
# Interactive wizard flow:
# 1. Select MCP servers to monitor
# 2. Configure transport type (stdio/SSE)
# 3. Set storage backend (memory/postgres)
# 4. Choose dashboard port
# → Generates candor.config.json

candor status
# Output:
# Candor Proxy v1.0.0
# ─────────────────────────────
# Status:     Running
# Proxy:      localhost:3100
# Dashboard:  localhost:3200
# WebSocket:  localhost:3101
#
# Active Sessions: 2
# Total Events:    1,847
# Uptime:          4h 23m
#
# Connected Upstreams:
#   ✓ filesystem (stdio)
#   ✓ github (SSE)
#   ✗ slack (disconnected)

1// candor.config.json
2{
3  "upstreams": [
4    {
5      "name": "filesystem",
6      "transport": "stdio",
7      "command": "npx",
8      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
9    },
10    {
11      "name": "sqlite",
12      "transport": "stdio",
13      "command": "npx",
14      "args": ["-y", "@modelcontextprotocol/server-sqlite", "db.sqlite"]
15    }
16  ]
17}

1// candor.config.json
2{
3  "upstreams": [
4    {
5      "name": "github",
6      "transport": "sse",
7      "url": "https://mcp.github.com/sse",
8      "headers": {
9        "Authorization": "Bearer ghp_xxxxxxxxxxxx"
10      }
11    }
12  ]
13}

// Supported wallets:
// - Phantom (browser extension)
// - Solflare (browser extension)
// - Any Wallet Standard compatible wallet
// The dashboard uses @solana/wallet-adapter-react
// Auth flow:
// 1. Click "Connect Wallet" → wallet popup
// 2. Approve connection → dashboard unlocks
// 3. Wallet address = account ID
// 4. Disconnect to return to demo mode

1// Connect to WebSocket
2const ws = new WebSocket('ws://localhost:3101');
3
4ws.onopen = () => {
5  console.log('Connected to Candor event stream');
6
7  // Subscribe to specific sessions (optional)
8  ws.send(JSON.stringify({
9    type: 'subscribe',
10    sessionId: 'session-uuid-here'
11  }));
12};
13
14ws.onmessage = (event) => {
15  const data = JSON.parse(event.data);
16
17  switch (data.type) {
18    case 'event':
19      // New MCP event intercepted
20      console.log(data.event);
21      break;
22    case 'session:start':
23      // New session began
24      console.log('New session:', data.sessionId);
25      break;
26    case 'session:end':
27      // Session completed
28      console.log('Session ended:', data.sessionId);
29      break;
30    case 'alert':
31      // Alert rule triggered
32      console.log('Alert:', data.alert);
33      break;
34  }
35};

1interface MCPEvent {
2  id: string;           // Unique event ID
3  sessionId: string;    // Parent session ID
4  timestamp: string;    // ISO 8601 timestamp
5  direction: 'request' | 'response';
6
7  // MCP fields
8  method: string;       // e.g., "tools/call", "resources/read"
9  toolName?: string;    // Tool name (for tool calls)
10  params?: object;      // Request parameters
11  result?: object;      // Response result
12
13  // Metadata
14  latencyMs?: number;   // Round-trip latency
15  costEstimate?: number; // Estimated USD cost
16  tokenCount?: {
17    input: number;
18    output: number;
19  };
20  status: 'success' | 'error';
21  error?: string;       // Error message (if status is 'error')
22}

// Create custom cost rate
PUT /api/cost-rates/custom-model
{
  "provider": "custom",
  "model": "my-fine-tuned-model",
  "inputPer1kTokens": 5.00,
  "outputPer1kTokens": 15.00,
  "currency": "USD"
}

// Create alert rule via API
POST /api/alert-rules
{
  "name": "High Error Rate",
  "condition": {
    "type": "error_rate",
    "threshold": 0.1,     // 10% error rate
    "window": "5m"        // Over a 5-minute window
  },
  "webhookUrl": "https://hooks.slack.com/services/xxx",
  "enabled": true
}

1// Webhook payload example
2{
3  "id": "alert-uuid",
4  "rule": "High Error Rate",
5  "severity": "warning",
6  "message": "Error rate exceeded 10% in the last 5 minutes",
7  "timestamp": "2026-02-23T14:30:00Z",
8  "session": {
9    "id": "session-uuid",
10    "agentId": "claude-desktop"
11  },
12  "event": {
13    "id": "event-uuid",
14    "method": "tools/call",
15    "toolName": "file_write",
16    "status": "error",
17    "error": "Permission denied"
18  }
19}

# Install Railway CLI
npm install -g @railway/cli
# Login
railway login
# Initialize project
railway init
# Add PostgreSQL
railway add --plugin postgresql
# Deploy
railway up
# Set environment variables
railway variables set DATABASE_URL=<auto-provided>
railway variables set PROXY_PORT=3100
railway variables set DASHBOARD_PORT=3200

1# Dockerfile
2FROM node:20-alpine AS base
3
4WORKDIR /app
5COPY package*.json ./
6RUN npm ci --production
7
8COPY . .
9RUN npm run build
10
11EXPOSE 3100 3200 3101
12
13CMD ["npm", "start"]

1# docker-compose.yml
2services:
3  candor:
4    build: .
5    ports:
6      - "3100:3100"
7      - "3200:3200"
8      - "3101:3101"
9    environment:
10      - DATABASE_URL=postgresql://candor:secret@db:5432/candor
11    depends_on:
12      - db
13
14  db:
15    image: postgres:16-alpine
16    environment:
17      POSTGRES_DB: candor
18      POSTGRES_USER: candor
19      POSTGRES_PASSWORD: secret
20    volumes:
21      - pgdata:/var/lib/postgresql/data
22
23volumes:
24  pgdata: