🏗️ Architecture & Launch Guide

Single source of truth for Neo Fleet architecture.

Quick Reference

Component	URL	Purpose
Landing	neo.themenonlab.com	Marketing site
Wizard	neo.themenonlab.com/wizard/	Customer onboarding
Dashboard	neo.themenonlab.com/wizard/dashboard.html	Agent management
Provisioning API	neo-provision-api-production.up.railway.app	Creates agents
Docs	neo.themenonlab.com/docs/	Setup guides

Architecture Overview

flowchart TB
  subgraph PUB["🌐 Public — GitHub Pages · menonpg/neo-agent"]
    direction LR
    L["Landing
index.html"]
    W["Wizard
/wizard/"]
    D["Docs
/docs/"]
  end
  API["⚙️ Provisioning API — Railway
validate creds · create service
inject secrets · deploy · return bot link"]
  subgraph AGENTS["🤖 Customer Agents — Railway · one service each"]
    direction LR
    A1["neo-customer-1
OpenClaw · fresh memory · own keys"]
    A2["neo-customer-2
OpenClaw · fresh memory · own keys"]
    A3["neo-customer-3
OpenClaw · fresh memory · own keys"]
  end
  W -- "POST /provision" --> API
  API -- "creates" --> AGENTS

┌─────────────────────────────────────────────────────────────────────┐
│                        PUBLIC (GitHub Pages)                         │
│                     menonpg/neo-agent repo                           │
│                                                                      │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐               │
│   │  Landing    │   │   Wizard    │   │    Docs     │               │
│   │  index.html │   │  /wizard/   │   │   /docs/    │               │
│   └─────────────┘   └──────┬──────┘   └─────────────┘               │
│                            │                                         │
└────────────────────────────┼─────────────────────────────────────────┘
                             │ POST /provision
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    PROVISIONING API (Railway)                        │
│                                                                      │
│   • Validates customer credentials                                   │
│   • Creates new Railway service for each customer                    │
│   • Injects secrets as env vars                                      │
│   • Deploys OpenClaw container                                       │
│   • Returns agent_id and Telegram bot link                           │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ Creates
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      CUSTOMER AGENTS (Railway)                       │
│                   One service per customer                           │
│                                                                      │
│   ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │
│   │  neo-customer-1 │  │  neo-customer-2 │  │  neo-customer-3 │     │
│   │                 │  │                 │  │                 │     │
│   │  • OpenClaw     │  │  • OpenClaw     │  │  • OpenClaw     │     │
│   │  • Fresh memory │  │  • Fresh memory │  │  • Fresh memory │     │
│   │  • Customer's   │  │  • Customer's   │  │  • Customer's   │     │
│   │    API keys     │  │    API keys     │  │    API keys     │     │
│   └─────────────────┘  └─────────────────┘  └─────────────────┘     │
│                                                                      │
│   Each agent has:                                                    │
│   • Isolated Railway service (~$5-10/mo compute)                     │
│   • 5GB persistent volume (/root/.openclaw/workspace)                │
│   • Customer's secrets as env vars (never in code)                   │
│   • Fresh MEMORY.md, SOUL.md from domain template                    │
└─────────────────────────────────────────────────────────────────────┘

Separation of Concerns

✅ PUBLIC (safe to expose)

• Landing page HTML
• Wizard UI (collects credentials client-side)
• Documentation
• Domain templates (general, biomedical, automotive)

🔐 PRIVATE (never exposed)

• Neo's home workspace (MEMORY.md, secrets)
• Provisioning API source
• Customer secrets (Railway env vars)
• Fleet registry (customer list, status)

Important: Each customer agent is completely isolated — separate Railway service, separate volume, own env vars. No access to other customers' data or Neo's home workspace.

Current State

✅ Working

Landing pageLive

Wizard UI (6-step)Live

Provisioning APIv2.1.0

DocsLive

Promo codesWorking

Domain templates3 available

⚠️ Beta-Ready (works but basic)

DashboardEmail lookup only

Fleet registryIn API, no public view

❌ Not Built (needed for paid)

Payment (Stripe)Missing

Payment webhookMissing

Provisioning gateMissing

Dashboard authMissing

Usage trackingMissing

Billing portalMissing

Promo Codes

Code	Effect
BETA2026	Free forever (beta tester)
FOUNDER	Free forever (founder access)
LAUNCH50	50% off first 3 months
FRIEND20	20% off first month

Cost Model

Per Customer Agent

Railway compute	~$5-10/mo
Railway volume (5GB)	Included
API calls	Customer's keys

Infrastructure (Fixed)

GitHub Pages	FREE
Provisioning API	~$5/mo
Supabase (registry)	Free tier

Margin at $29/mo

Revenue:$29.00

- Railway:-$7.00

- Stripe fees:-$1.14

Gross margin:~$21 (72%)

Quick Commands

Check provisioning API health

curl https://neo-provision-api-production.up.railway.app/health

Test provision (dry run)

curl -X POST https://neo-provision-api-production.up.railway.app/provision \
  -H "Content-Type: application/json" \
  -d '{"customer_name":"test"}'
# Returns: {"success":false,"error":"Missing required field: customer_email"}

This document is the single source of truth for Neo Fleet architecture. Update it when things change.

← Back to Neo