neo-agent

Neo MVP — Lean Architecture

Minimal viable fleet: Railway for agents only, everything else static/free.

---

Cost Analysis: Original vs MVP

Original Design Costs

Component	Service	Monthly Cost
Dashboard	Vercel Pro	$20
API Worker	Cloudflare Workers	$5+
Database	Supabase Pro	$25
Agent (each)	Railway	~$5-10
Total (10 agents)		$100-150/mo

MVP Design Costs

Component	Service	Monthly Cost
Setup Wizard	GitHub Pages	FREE
Dashboard	GitHub Pages	FREE
Fleet Config	JSON in repo	FREE
Agent (each)	Railway	~$5-10
Total (10 agents)		$50-100/mo

Savings: 50%+ by eliminating Supabase/Vercel/Workers

---

MVP Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         NEO MVP STACK                            │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  GITHUB PAGES (FREE)                                             │
│  menonpg.github.io/neo-agent/                                   │
│                                                                  │
│  ├── /wizard/     → Customer onboarding form                    │
│  ├── /dashboard/  → Fleet status viewer (static)                │
│  └── /docs/       → Setup guides                                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ Customer submits form
                              │ (GitHub Issue or Google Form)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  GITHUB REPO (FREE)                                              │
│  menonpg/neo-fleet (private)                                    │
│                                                                  │
│  ├── fleet.json         → Agent registry                        │
│  ├── customers/         → Customer configs                      │
│  │   ├── lw-auto.json                                           │
│  │   └── anasto-1.json                                          │
│  └── .github/workflows/ → Automation                            │
│      ├── spawn-agent.yml                                        │
│      └── health-check.yml                                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ GitHub Action spawns
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  RAILWAY (PAY PER AGENT)                                         │
│                                                                  │
│  ├── neo-lw-auto        → LW Automotive agent                   │
│  ├── neo-anasto-1       → Anasto customer agent                 │
│  └── neo-internal       → Our internal agent                    │
│                                                                  │
│  Each ~$5-10/mo depending on usage                              │
└─────────────────────────────────────────────────────────────────┘

---

How It Works

1. Customer Onboarding (Manual/Semi-Auto)

Option A: Google Form (Simplest)

Google Form → Google Sheet → We review → Spawn manually

Option B: GitHub Issue Template

# .github/ISSUE_TEMPLATE/new-agent.yml
name: Request New Agent
description: Request a Neo agent for your team
body:
  - type: input
    id: company
    attributes:
      label: Company Name
    validations:
      required: true
      
  - type: dropdown
    id: provider
    attributes:
      label: AI Provider
      options:
        - GitHub Copilot
        - OpenAI
        - Anthropic
    validations:
      required: true
      
  - type: input
    id: github_token
    attributes:
      label: GitHub PAT (we'll delete after setup)
      description: "Create at github.com/settings/tokens"
    validations:
      required: true
      
  - type: dropdown
    id: channel
    attributes:
      label: Communication Channel
      options:
        - Telegram
        - Discord
        - API Only

Customer submits issue → We validate token → Spawn agent → Close issue

2. Fleet Registry (JSON in Repo)

// fleet.json
{
  "agents": [
    {
      "id": "neo-lw-auto",
      "customer": "LW Automotive",
      "railway_service_id": "srv_xxx",
      "railway_url": "https://neo-lw-auto.up.railway.app",
      "status": "running",
      "provider": "github-copilot",
      "channel": "telegram",
      "domain": "automotive",
      "created_at": "2026-06-28"
    },
    {
      "id": "neo-anasto-1",
      "customer": "CJ Shores",
      "railway_service_id": "srv_yyy",
      "railway_url": "https://neo-anasto-1.up.railway.app",
      "status": "running",
      "provider": "openai",
      "channel": "discord",
      "domain": "biomedical",
      "created_at": "2026-06-28"
    }
  ]
}

3. Static Dashboard (GitHub Pages)

<!-- dashboard/index.html -->
<!DOCTYPE html>
<html>
<head>
  <title>Neo Fleet Dashboard</title>
  <script src="https://cdn.tailwindcss.com"></script>
</head>
<body class="bg-gray-100 p-8">
  <h1 class="text-2xl font-bold mb-6">Neo Fleet</h1>
  
  <div id="agents" class="grid grid-cols-3 gap-4">
    <!-- Populated by JS -->
  </div>

  <script>
    async function loadFleet() {
      // Fetch from raw GitHub (or local JSON)
      const res = await fetch('https://raw.githubusercontent.com/menonpg/neo-fleet/main/fleet.json');
      const data = await res.json();
      
      const container = document.getElementById('agents');
      container.innerHTML = data.agents.map(agent => `
        <div class="bg-white rounded-lg shadow p-4">
          <div class="flex justify-between">
            <h3 class="font-semibold">${agent.id}</h3>
            <span class="px-2 py-1 text-xs rounded ${
              agent.status === 'running' ? 'bg-green-100 text-green-800' : 'bg-gray-100'
            }">${agent.status}</span>
          </div>
          <p class="text-gray-500 text-sm">${agent.customer}</p>
          <div class="mt-2 text-sm">
            <span class="text-gray-400">Provider:</span> ${agent.provider}<br>
            <span class="text-gray-400">Channel:</span> ${agent.channel}
          </div>
        </div>
      `).join('');
    }
    
    loadFleet();
  </script>
</body>
</html>

4. Spawn via GitHub Action

# .github/workflows/spawn-agent.yml
name: Spawn Agent

on:
  workflow_dispatch:
    inputs:
      agent_id:
        description: 'Agent ID (e.g., neo-customer-1)'
        required: true
      customer:
        description: 'Customer name'
        required: true
      provider:
        description: 'AI provider'
        required: true
        type: choice
        options:
          - github-copilot
          - openai
          - anthropic
      domain:
        description: 'Domain template'
        required: true
        type: choice
        options:
          - general
          - biomedical
          - automotive

jobs:
  spawn:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Create Railway Service
        env:
          RAILWAY_TOKEN: $
        run: |
          # Create service via Railway CLI or API
          SERVICE_ID=$(curl -s -X POST https://backboard.railway.app/graphql/v2 \
            -H "Authorization: Bearer $RAILWAY_TOKEN" \
            -H "Content-Type: application/json" \
            -d '{
              "query": "mutation { serviceCreate(input: { projectId: \"'$'\", name: \"'$'\" }) { id } }"
            }' | jq -r '.data.serviceCreate.id')
          
          echo "SERVICE_ID=$SERVICE_ID" >> $GITHUB_ENV
          
      - name: Set Environment Variables
        env:
          RAILWAY_TOKEN: $
        run: |
          # Set env vars based on provider
          # (Customer provides secrets via separate secure channel)
          
      - name: Update Fleet Registry
        run: |
          # Add to fleet.json
          jq '.agents += [{
            "id": "$",
            "customer": "$",
            "railway_service_id": "'$SERVICE_ID'",
            "status": "deploying",
            "provider": "$",
            "domain": "$",
            "created_at": "'$(date +%Y-%m-%d)'"
          }]' fleet.json > fleet.tmp && mv fleet.tmp fleet.json
          
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add fleet.json
          git commit -m "Add agent: $"
          git push

5. Health Check Cron

# .github/workflows/health-check.yml
name: Fleet Health Check

on:
  schedule:
    - cron: '*/30 * * * *'  # Every 30 min
  workflow_dispatch:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check Agent Health
        run: |
          FLEET=$(cat fleet.json)
          UPDATED=false
          
          for agent in $(echo $FLEET | jq -r '.agents[] | @base64'); do
            _jq() { echo $agent | base64 -d | jq -r $1; }
            
            URL=$(_jq '.railway_url')
            ID=$(_jq '.id')
            
            if curl -sf "$URL/health" > /dev/null 2>&1; then
              STATUS="running"
            else
              STATUS="unhealthy"
            fi
            
            # Update status in fleet.json
            FLEET=$(echo $FLEET | jq "(.agents[] | select(.id == \"$ID\") | .status) = \"$STATUS\"")
            UPDATED=true
          done
          
          if [ "$UPDATED" = true ]; then
            echo "$FLEET" > fleet.json
            git config user.name "GitHub Actions"
            git config user.email "actions@github.com"
            git add fleet.json
            git commit -m "Health check: $(date +%Y-%m-%d-%H%M)" || true
            git push || true
          fi

---

Secret Handling (MVP Approach)

Since we don’t have a backend, secrets are handled manually:

Option 1: Direct Railway Dashboard

1. Customer provides token via secure channel (Signal, encrypted email)
2. We manually add to Railway service env vars
3. Delete from our side after setting

Option 2: Railway CLI in Action (More Automated)

# In spawn workflow, customer token passed as input (deleted after)
- name: Set Customer Secrets
  env:
    RAILWAY_TOKEN: $
    CUSTOMER_TOKEN: $
  run: |
    # Set via Railway API
    curl -X POST ... -d '{"name": "GITHUB_TOKEN", "value": "'$CUSTOMER_TOKEN'"}'
    
    # Token is not stored in git, only in Railway

Option 3: GitHub Secrets (Per Customer)

For each customer, create repository secret:

• CUSTOMER_LW_GITHUB_TOKEN
• CUSTOMER_ANASTO_OPENAI_KEY

Reference in spawn workflow. Secure but requires manual secret creation.

---

File Structure

menonpg/neo-agent (public)
├── README.md
├── docs/
│   ├── GITHUB-PAT-SETUP.md
│   └── ...
├── wizard/              ← GitHub Pages: onboarding form
│   └── index.html
├── dashboard/           ← GitHub Pages: fleet viewer
│   └── index.html
├── templates/           ← Domain templates
│   ├── general/
│   ├── biomedical/
│   └── automotive/
└── Dockerfile           ← Base agent image

menonpg/neo-fleet (private)
├── fleet.json           ← Agent registry
├── customers/           ← Customer configs (no secrets)
│   ├── lw-auto.json
│   └── anasto-1.json
└── .github/workflows/
    ├── spawn-agent.yml
    └── health-check.yml

---

MVP Limitations (Accept for Now)

Feature	Full Version	MVP
Onboarding	Automated wizard	GitHub Issue / Form
Secret entry	Web form + validate	Manual via secure channel
Dashboard	Live updates	Refresh to see changes
Billing	Stripe integration	Manual invoicing
Health alerts	Slack/email	Check dashboard
Secret rotation	One-click	Manual Railway update

---

Migration Path

MVP → Full Version when needed:

1. Add Supabase when we need real-time updates or complex queries
2. Add Worker API when we need token validation before spawn
3. Add Stripe when we have >10 paying customers
4. Add proper dashboard when MVP friction becomes a problem

---

Cost Summary

Scenario	Monthly Cost
Just us (1-2 internal agents)	$10-20
+ 5 customer agents	$35-70
+ 10 customer agents	$60-120

All infrastructure (wizard, dashboard, registry) = FREE via GitHub

---

Ship the MVP. Add complexity when revenue justifies it.