Technical
Platform Architecture
A deep dive into how Lobstack provisions dedicated infrastructure, runs AI agents, and connects everything together.
💡
Architecture Overview
Lobstack is a multi-tenant SaaS platform that provisions dedicated VMs for each AI agent. Every agent runs its own OpenClaw instance with isolated compute, memory, and network access.
System Diagram#
The platform consists of four main layers that communicate via authenticated HTTP APIs.
High-Level Architecture
┌─────────────────────────────────────────────────────────────┐
│ User (Browser / API) │
└─────────────────────────────┬───────────────────────────────┘
│
▼
┌───────────────────────────┐
│ Next.js Application │
│ (Vercel Serverless) │
│ │
│ ┌─────────┐ ┌─────────┐ │
│ │ React │ │ 56 API │ │
│ │Dashboard│ │ Routes │ │
│ └─────────┘ └────┬────┘ │
└───────────────────┼───────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Supabase │ │ Stripe │ │ Cloud Provider │
│ (PostgreSQL + │ │ (Payments & │ │ (Hetzner / DO │
│ Auth + RLS) │ │ Subscriptions)│ │ / Vultr) │
└──────────────────┘ └────────────────┘ └───────┬────────┘
│
▼
┌──────────────────┐
│ Agent VM │
│ │
│ ┌─────────────┐ │
│ │Agent Bridge │ │
│ │ (REST API) │ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ OpenClaw │ │
│ │ (AI Runtime)│ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ MCP Servers │ │
│ │ (10+ tools) │ │
│ └─────────────┘ │
└──────────────────┘Architecture Layers#
1. Frontend — Next.js Dashboard#
The user-facing application is built with Next.js 16, React 19, and Tailwind CSS 4. It provides:
| Component | Purpose |
|---|---|
| Dashboard | 8-panel agent control center (Overview, Agent, Chat, Skills, Sandbox, Memory, Logs, Settings) |
| Onboarding | 3-step setup wizard: model → plan → deploy |
| Docs Site | 30+ pages of documentation with sidebar navigation |
| Admin Panel | 12-section admin dashboard with Master Terminal |
| Landing Page | Marketing site with Spline 3D hero, pricing, and social proof |
2. API Layer — 56 Serverless Routes#
All backend logic runs as serverless functions on Vercel. Routes are organized by domain:
| Domain | Routes | Purpose |
|---|---|---|
| /api/agent/* | 30+ | Agent lifecycle, chat, config, skills, memory, workflows, analytics |
| /api/admin/* | 20+ | Admin operations, monitoring, payments, user management |
| /api/checkout | 1 | Stripe checkout session creation |
| /api/webhooks/stripe | 1 | Stripe webhook handler (5 event types) |
| /api/cron/health | 1 | Health check + auto-recovery (runs every minute) |
| /api/affiliate/* | 2 | Affiliate registration and stats |
3. Database — Supabase PostgreSQL#
All state is stored in a Supabase-managed PostgreSQL database with Row Level Security (RLS) enabled on every table. The schema includes 19 tables:
| Table Group | Tables | Purpose |
|---|---|---|
| Identity | users, subscriptions | User accounts, billing, Stripe mapping |
| Agent | agent_instances, agent_configs, agent_skills, agent_memory | Agent state, configuration, integrations, knowledge |
| Messaging | messages, chat_sessions | Chat history, session grouping |
| Automation | workflows, workflow_triggers, workflow_executions | Workflow definitions, triggers (cron/webhook/event), execution tracking |
| Webhooks | webhooks, webhook_deliveries | Outbound webhook config and delivery log |
| Monitoring | agent_logs, health_checks, token_usage | Operational logs, health history, token consumption |
| Affiliate | affiliates, referrals, commissions | Partner program, referral tracking, commission payouts |
4. Infrastructure — Dedicated VMs#
Each agent runs on a dedicated virtual machine provisioned via cloud provider APIs. The provisioning flow:
Agent Provisioning Flow
User selects plan → Stripe checkout → Webhook fires
│
▼
provisionAgent()
│
┌───────────┼───────────┐
▼ ▼ ▼
Create VM Create DB Seed Config
(cloud-init) Records (SOUL.md, etc.)
│
▼
cloud-init script runs:
├── Install Node.js 22
├── Install Python 3.11
├── Install OpenClaw 2026.2.26
├── Configure MCP servers
├── Start agent bridge
└── POST /api/agent/provisioned
│
▼
Agent online (status: running)
Heartbeat every 30 seconds| Plan | vCPU | RAM | Storage | Messages/mo |
|---|---|---|---|---|
| Starter | 2 | 2 GB | 50 GB SSD | 1,000 |
| Pro | 2 | 4 GB | 80 GB SSD | 5,000 |
| Performance | 4 | 8 GB | 160 GB SSD | 15,000 |
| Enterprise | 8 | 32 GB | 320 GB SSD | 50,000 |
Key Data Flows#
Chat Message Flow#
User → Agent → Response
Dashboard sends POST /api/agent/chat
│
▼
API validates auth + checks message quota
│
▼
Forwards to Agent Bridge (HTTP → agent VM:3001)
│
▼
Bridge → OpenClaw → AI Model (Claude/GPT/Gemini)
│
▼
Response returns through same path
│
▼
Bridge async: POST /api/agent/messages (store + extract memories)Health Check & Auto-Recovery#
A Vercel Cron job runs every minute to monitor all agents:
| Check | Threshold | Action |
|---|---|---|
| Stuck provisioning (silent) | 8 minutes | Auto-rebuild with provider rotation |
| Stuck provisioning (total) | 25 minutes | Mark error, preserve server for inspection |
| Health check failure | 5 consecutive | Mark agent as error |
| Heartbeat timeout | 5 minutes | Flag as potentially unhealthy |
Security Architecture#
Security is enforced at every layer of the stack:
| Layer | Mechanism |
|---|---|
| Authentication | Supabase JWT with PKCE flow, auto-refresh via middleware |
| Authorization | Row Level Security (RLS) on all 19 database tables |
| Agent Bridge | Shared secret (X-Agent-Secret header) + agent ID validation |
| Admin API | Separate admin secret (X-Admin-Secret header) |
| Stripe Webhooks | HMAC-SHA256 signature verification |
| Outgoing Webhooks | HMAC-SHA256 signature in X-Lobstack-Signature header |
| Agent Isolation | Dedicated VM per agent, loopback-only gateway binding |
| OpenClaw Gateway | Sandboxed mode, token auth, security audit on provision |
Technology Stack#
| Category | Technology | Version |
|---|---|---|
| Framework | Next.js | 16.1.6 |
| UI | React | 19.2.3 |
| Styling | Tailwind CSS | 4.x |
| Animation | Framer Motion | 12.x |
| Language | TypeScript | 5.9.3 |
| Database | Supabase (PostgreSQL) | Latest |
| Auth | Supabase Auth | JWT + PKCE |
| Payments | Stripe | 20.3.1 |
| AI Runtime | OpenClaw | 2026.2.26 |
| Tool Protocol | MCP (Model Context Protocol) | 1.25.3 |
| Hosting | Vercel | Serverless |
| Compute | Hetzner / DigitalOcean / Vultr | On-demand VMs |
| Charts | D3.js | 7.9.0 |
Scaling & Reliability#
Lobstack is designed for horizontal scaling:
| Component | Scaling Strategy |
|---|---|
| API | Vercel serverless auto-scaling (per-request) |
| Database | Supabase managed PostgreSQL (vertical + read replicas) |
| Agent VMs | One dedicated VM per agent (horizontal by nature) |
| Health checks | Parallel batches of 10 agents, ~1 min for 100 agents |
| Webhooks | Fire-and-forget pattern, logged for retry |
| Memory extraction | Async background, rate-limited per agent (1/60s) |
✅
Want to dive deeper?
Check out the Security docs for encryption, Vault secrets, and compliance details. See OpenClaw Integration for runtime internals.