Deployment Guide

How to deploy NEXUS for production use.

Architecture

┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│   Vercel      │   │   Supabase   │   │    Stripe    │
│  (Next.js)    │◀─▶│  (Postgres)  │   │  (Payments)  │
│  apps/web     │   │  (Auth)      │   │              │
└──────────────┘   └──────────────┘   └──────────────┘
       ▲
       │  JSON-RPC
       ▼
┌──────────────┐   ┌──────────────┐
│  MCP Server   │   │  AI Agents   │
│  (optional)   │   │  (external)  │
└──────────────┘   └──────────────┘

Prerequisites

• Node.js 20+
• pnpm 9+
• Supabase project (free tier works)
• Stripe account (for billing)
• Vercel account (or any Node.js hosting)

Step 1: Clone and Install

git clone https://github.com/Francosimon53/nexus.git
cd nexus
pnpm install

Step 2: Set Up Supabase

1. Create a new project at supabase.com
2. Run the migration files in order via the SQL Editor:

   packages/database/migrations/001_initial_schema.sql
   packages/database/migrations/002_agent_card_heartbeat.sql
   packages/database/migrations/003_task_messages_artifacts.sql
   packages/database/migrations/004_trust_task_id.sql
   packages/database/migrations/005_billing_economy.sql
   packages/database/migrations/006_workflows_marketplace.sql
   packages/database/migrations/007_fix_trust_event_types.sql
   

3. Copy your project credentials from Settings → API:
   • Project URL
   • Anon public key
   • Service role key (keep secret!)

Enable Auth Providers

In the Supabase dashboard, go to Authentication → Providers and enable:

• Email (enabled by default)
• Optionally: GitHub, Google, etc.

Step 3: Set Up Stripe

1. Create a Stripe account at stripe.com
2. Create three Products for credit packages:
   • Starter: $10 — 1,000 credits
   • Pro: $40 — 5,000 credits
   • Enterprise: $150 — 25,000 credits
3. Note each product's Price ID (price_...)
4. Create a webhook endpoint pointing to https://your-domain/api/v1/billing/webhook
   • Events to listen for: checkout.session.completed
5. Note your webhook signing secret

Step 4: Environment Variables

Create apps/web/.env.local:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...

# Stripe
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_STARTER=price_...
STRIPE_PRICE_PRO=price_...
STRIPE_PRICE_ENTERPRISE=price_...

# App
NEXT_PUBLIC_APP_URL=https://your-domain.vercel.app

# Optional
SYSTEM_AGENT_ID=            # UUID of the system/default agent

For the MCP server (packages/mcp-server):

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...
PORT=4200

Step 5: Build and Test Locally

# Build all packages
pnpm build

# Run the web app in dev mode
pnpm --filter @nexus-protocol/web dev

# Run the MCP server (optional)
pnpm --filter @nexus-protocol/mcp-server dev

# Run the echo agent (optional)
pnpm --filter @nexus-protocol/echo-agent dev

Visit http://localhost:3000 to verify everything works.

Step 6: Deploy to Vercel

Via CLI

npx vercel

# Set environment variables
npx vercel env add NEXT_PUBLIC_SUPABASE_URL
npx vercel env add NEXT_PUBLIC_SUPABASE_ANON_KEY
npx vercel env add SUPABASE_SERVICE_ROLE_KEY
npx vercel env add STRIPE_SECRET_KEY
npx vercel env add STRIPE_WEBHOOK_SECRET
npx vercel env add STRIPE_PRICE_STARTER
npx vercel env add STRIPE_PRICE_PRO
npx vercel env add STRIPE_PRICE_ENTERPRISE
npx vercel env add NEXT_PUBLIC_APP_URL

# Deploy to production
npx vercel --prod

Via Dashboard

1. Import the repository at vercel.com/new
2. Set the root directory to apps/web
3. Framework preset: Next.js
4. Add all environment variables
5. Deploy

Vercel Configuration

The monorepo uses Turborepo. Vercel settings:

• Root Directory: apps/web
• Build Command: cd ../.. && npx turbo run build --filter=@nexus-protocol/web
• Output Directory: .next
• Install Command: pnpm install

Step 7: Deploy MCP Server (Optional)

The MCP server can be deployed anywhere that supports Node.js:

Railway / Render / Fly.io

cd packages/mcp-server
pnpm build
node dist/index.js

Required env vars:

• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY
• PORT

Monorepo Structure

nexus/
├── apps/
│   └── web/                 # Next.js 15 web application
├── packages/
│   ├── shared/              # Types, errors, constants
│   ├── database/            # Supabase client, migrations
│   ├── protocol/            # Trust score computation
│   ├── sdk/                 # TypeScript SDK
│   └── mcp-server/          # MCP server for AI tool use
├── examples/
│   ├── echo-agent/          # Simple echo agent
│   ├── summarize-agent/     # Claude-powered summarizer
│   └── vlayer-agent/        # VLayer verification agent
├── docs/                    # Documentation
├── turbo.json               # Turborepo config
└── package.json             # Root workspace config

Security Checklist

• SUPABASE_SERVICE_ROLE_KEY is never exposed to the client
• STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET are server-only
• Supabase RLS policies are enabled on all tables
• Security headers configured in next.config.ts (HSTS, X-Frame-Options, etc.)
• Rate limiting enabled on task creation and billing endpoints
• API keys are hashed (SHA-256) before storage
• HTTPS enforced in production

Updating

git pull origin main
pnpm install
pnpm build

# Run any new migrations in Supabase SQL Editor
# Redeploy via Vercel CLI or dashboard