Skip to main content

Self-Hosting

Deploy the Lucid stack on your own infrastructure for full data sovereignty and custom deployment requirements.

Architecture

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   TrustGate     │  │    MCPGate      │  │  Lucid-L2 API   │
│   (:4010)       │  │    (:4020)      │  │   (:3001)       │
│  LLM proxy      │  │  Tool gateway   │  │  Receipts/epochs│
└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
         │                    │                     │
         └──────────┬─────────┘                     │
              ┌─────▼──────┐                  ┌─────▼──────┐
              │ PostgreSQL  │                  │   Solana    │
              │ (Supabase)  │                  │  (devnet)   │
              └─────────────┘                  └────────────┘

Prerequisites

  • Docker and Docker Compose
  • PostgreSQL 15+ (or Supabase self-hosted)
  • Solana RPC endpoint (Helius, QuickNode, or local validator)
  • Ed25519 keypair for receipt signing
  • Node.js 20+

Docker Compose

version: "3.8"
services:
  trustgate:
    build: ./lucid-plateform-core
    command: npx tsx apps/trustgate-api/src/server.ts
    ports: ["4010:4010"]
    environment:
      DATABASE_URL: postgresql://lucid:password@db:5432/lucid
      LITELLM_BASE_URL: http://litellm:4000
      PORT: 4010
    depends_on: [db, litellm]

  mcpgate:
    build: ./mcpgate
    ports: ["4020:4020"]
    environment:
      DATABASE_URL: postgresql://lucid:password@db:5432/lucid
      PORT: 4020
      GITHUB_TOKEN: ${GITHUB_TOKEN}
      SLACK_TOKEN: ${SLACK_TOKEN}
    depends_on: [db]

  lucid-api:
    build: ./Lucid-L2/offchain
    ports: ["3001:3001"]
    environment:
      DATABASE_URL: postgresql://lucid:password@db:5432/lucid
      SOLANA_RPC_URL: ${SOLANA_RPC_URL}
      SIGNER_PRIVATE_KEY: ${SIGNER_PRIVATE_KEY}
    depends_on: [db]

  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    ports: ["4000:4000"]
    volumes:
      - ./litellm-config.yaml:/app/config.yaml
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}

  db:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: lucid
      POSTGRES_PASSWORD: password
      POSTGRES_DB: lucid

volumes:
  pgdata:

Configuration

1. Generate a Session Signer

# Generate Ed25519 keypair for receipt signing
node -e "
const { generateKeyPairSync } = require('crypto');
const { privateKey } = generateKeyPairSync('ed25519');
console.log(privateKey.export({ type: 'pkcs8', format: 'pem' }));
" > signer.pem

2. Configure LiteLLM

Create litellm-config.yaml for your preferred LLM providers:
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-3-sonnet
    litellm_params:
      model: anthropic/claude-3-sonnet-20240229
      api_key: os.environ/ANTHROPIC_API_KEY

3. Run Migrations

# Apply all database migrations
docker compose exec lucid-api node scripts/migrate.js
docker compose exec mcpgate npm run migrate

4. Start the Stack

docker compose up -d

Verify Installation

# Check TrustGate
curl http://localhost:4010/health

# Check MCPGate
curl http://localhost:4020/health

# Check Lucid-L2 API
curl http://localhost:3001/health

# Test inference
curl -X POST http://localhost:4010/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Networking

ServicePortProtocolExternal?
TrustGate4010HTTPYes (clients connect here)
MCPGate4020HTTPYes (agents connect here)
Lucid-L2 API3001HTTPOptional (internal receipts)
LiteLLM4000HTTPNo (internal only)
PostgreSQL5432TCPNo (internal only)

Security Considerations

  • Never expose PostgreSQL or LiteLLM ports externally
  • Use TLS termination (nginx/Caddy) in front of TrustGate and MCPGate
  • Rotate the session signer keypair periodically
  • Set ADMIN_API_KEY for MCPGate control plane access
  • Store secrets in a vault, not in docker-compose.yaml