Sovra

Ship AI products. Not infrastructure.

Open-source platform for building multi-tenant AI agent applications.
Auth, billing, MCP tools, vector search, multi-agent collaboration — in one repo.

_{A ByteWorthy product · byteworthy.io}

Quick Start  |   Features  |   Stack  |   Architecture  |   Deploy  |   Contribute

Every AI SaaS boilerplate gives you auth and billing. None give you the AI infrastructure. Every agent framework gives you LLM orchestration. None give you the SaaS wrapper. Sovra is both. One repo. One command. Production-ready.

Why Sovra?

You want to build an AI agent product. So you start wiring up auth, multi-tenancy, vector search, MCP tools, real-time collaboration, billing...

Three months later, you still haven't shipped a single AI feature.

Sovra eliminates that. Clone it, run it, build on it. What takes teams 3+ months, you get in one git clone.

🚀 Quick Start

git clone https://github.com/ByteWorthyLLC/sovra.git
cd sovra && pnpm install
supabase start              # Local Postgres + Auth + pgvector
cp .env.example .env.local  # Add Supabase keys from output
cd packages/web && pnpm dev # Open http://localhost:3000

That's it. Multi-tenant auth, vector database, agent runtime, real-time collaboration. Running locally.

Full setup guide (prerequisites + Go worker)

Prerequisites

• Node.js 18+ and pnpm 8+
• Go 1.22+ (for the agent worker service)
• Docker (for local Supabase)
• Supabase CLI

Step-by-step

# 1. Clone and install dependencies
git clone https://github.com/ByteWorthyLLC/sovra.git
cd sovra
pnpm install

# 2. Start local Supabase (Postgres + Auth + pgvector)
supabase start
# Copy the API URL and anon/service_role keys from the output

# 3. Configure environment
cp .env.example .env.local
cp packages/web/.env.example packages/web/.env.local
# Fill in the Supabase keys from step 2

# 4. Start the web app
cd packages/web && pnpm dev
# Open http://localhost:3000

# 5. (Optional) Start the Go worker for agent features
cd packages/worker
go mod download
go run ./cmd/worker

Environment Variables

See .env.example for all options. Only Supabase keys are required — Stripe, Sentry, PostHog, and Upstash are optional and gracefully disabled when not configured.

✨ What You Get

SaaS Layer

Everything you'd spend months building before writing a single AI feature:

	Feature	Details
🔒	Multi-tenant auth	Email, magic links, OAuth (Google, GitHub). Swappable via AuthAdapter interface.
🛡	Tenant isolation	Row-level security at the database. Postgres enforces it — not middleware, not app logic.
👥	Roles & permissions	Owner, admin, member, viewer. Database-backed, tenant-configurable.
📨	Invite system	Email invitations + shareable links. Works with or without SMTP.
💳	Billing	Stripe integration — plans, usage tracking, customer portal.
🔑	API keys	Scoped generation with rate limiting and audit logging.

AI Layer

The part nobody else ships:

	Feature	Details
🧩	MCP native	Full Model Context Protocol client AND server. Your agents use tools the ecosystem way.
🔍	Vector search	pgvector inside your existing Postgres. Semantic search, hybrid search, tenant-scoped.
🤖	Agent runtime	Custom models, system prompts, tool assignments. Streaming via Vercel AI SDK.
🤝	Multi-agent workspaces	5 collaboration modes (round-robin, hierarchical, democratic, parallel, debate). Shared memory. Conflict resolution.
🧠	Memory strategies	Full history, summary compression, vector retrieval, or hybrid.
🛠	Built-in tools	File ops, web search, URL fetch, DB query, semantic search. All MCP-compliant. All tenant-scoped.

Production Layer

Ship it, don't just demo it:

	Feature	Details
☁	Deploy anywhere	Docker, Railway, AWS, GCP. Self-hosted. Your data, your infrastructure.
📊	Admin dashboard	Tenant management, user management, system health, audit logs.
🚨	Monitoring	Sentry for errors, PostHog for analytics. Pre-wired.
🔏	Security hardened	CSP, HSTS, rate limiting, JWT verification, input validation. Production-ready.

🔧 The Stack

Frontend       Next.js 15 (App Router) + TypeScript + Tailwind + shadcn/ui
Agent Worker   Go 1.22+ with Gin + gRPC
Database       Supabase PostgreSQL + pgvector + Row Level Security
Auth           Supabase Auth (swappable via AuthAdapter)
Real-time      Socket.IO (Go server + React client)
AI SDK         Vercel AI SDK + MCP SDK
Billing        Stripe
Monitoring     Sentry + PostHog

Why these choices?

Why Go for the worker? Agent orchestration is I/O bound with bursts of CPU. Go's goroutines handle thousands of concurrent agent sessions on a single node. Python can't.

Why Supabase? Postgres + pgvector + auth + real-time + RLS in one service. No separate vector database bill. No separate auth service. Everything in one place, and you own the data.

Why not NextAuth/Clerk/Auth0? Sovra ships with Supabase Auth by default (zero config). But the AuthAdapter interface means you can swap to any provider by implementing 5 methods. No lock-in.

🏗 Architecture

                    ┌─────────────────────────────────┐
                    │        Next.js Frontend          │
                    │     (App Router, AI SDK, UI)     │
                    └──────────┬──────────┬────────────┘
                               │          │
                          API  │          │  Socket.IO / gRPC
                               │          │
                    ┌──────────▼──┐  ┌────▼──────────────┐
                    │  Supabase   │  │    Go Worker       │
                    │  Auth + DB  │  │  Agents + MCP      │
                    │  + RLS      │  │  + Real-time       │
                    └──────┬──────┘  └────┬───────────────┘
                           │              │
                    ┌──────▼──────────────▼──────┐
                    │   PostgreSQL + pgvector     │
                    │   (Tenant-isolated, RLS)    │
                    └────────────────────────────┘

📦 Project Structure

sovra/
├── packages/
│   ├── web/           # Next.js 15 frontend + API routes
│   ├── worker/        # Go agent worker (MCP server, Socket.IO, gRPC)
│   └── shared/        # Shared TypeScript types and schemas
├── supabase/
│   └── migrations/    # 7 database migrations (apply with supabase db push)
├── docker/            # Docker Compose (dev + prod)
├── platform/          # Deployment configs (AWS, GCP, Railway)
├── docs/              # Deployment guide, env var reference
├── .github/           # CI/CD workflows
└── .env.example       # All config options with descriptions

🚀 Deploy

Docker

docker compose -f docker/compose.prod.yaml up -d

Railway / Vercel / Fly.io

Deploy the Next.js app to any Node.js platform. Deploy the Go worker as a separate service. Point both at your Supabase project.

Environment Variables

All required and optional variables are documented in .env.example. At minimum:

Variable	Required	Description
NEXT_PUBLIC_SUPABASE_URL	Yes	Your Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	Yes	Supabase anonymous key
SUPABASE_SERVICE_ROLE_KEY	Yes	Supabase service role key (server-side)
DATABASE_URL	Worker	Direct Postgres connection for Go worker
STRIPE_SECRET_KEY	No	Enables billing features
OPENAI_API_KEY	No	Enables AI agent chat
SENTRY_DSN	No	Enables error tracking

🤝 Who This Is For

• Indie hackers building AI-powered SaaS — skip 3 months of infrastructure work
• Startups that need multi-tenant AI agents on day one
• Agencies building white-label AI solutions with tenant isolation — see also Klienta, a paid agency-vertical boilerplate built on Sovra
• Enterprise teams evaluating self-hosted alternatives to closed-source agent platforms
• Open-source contributors looking for a solid, extensible AI platform foundation

Who This Is NOT For

• Simple chatbot wrapper? Use OpenWebUI
• Agent framework only (no SaaS)? Use LangGraph or CrewAI
• Need a hosted solution? Sovra is self-hosted only
• Running an AI agency with multiple paying clients and need per-client branding, custom domains, and usage-based billing? → Use Klienta (paid boilerplate built on Sovra)

🤝 Built on Sovra

Sovra is the open-source AI platform foundation.

• Need a ready-made agency vertical on top (white-label portals, custom domains, metered billing)? Use Klienta.
• Need a ready-made healthcare vertical (FHIR R4, HL7 v2, X12 EDI, PHI controls, compliance scaffolding)? Use Clynova.

You're building...	Use
A product for end users	Sovra (this repo, free, MIT)
An agency with multiple paying clients	Klienta (paid, built on Sovra)
A healthcare AI product with interoperability/compliance requirements	Clynova (paid, built after Sovra foundations)

📋 Roadmap

Phase	Status	What Ships
Foundation	✅	Monorepo, database schema, Docker, dev environment
Core Infrastructure	✅	Supabase auth, multi-tenancy, RBAC, invitations
Agent Core	✅	Agent CRUD, chat interface, streaming, AI provider adapters
AI Features	✅	MCP client/server, built-in tools, vector storage, tool tracking
Multi-Agent	✅	Workspaces, 5 collab modes, 4 memory strategies, Socket.IO
Production Ready	✅	Stripe billing, admin dashboard, API keys, Sentry + PostHog, CI/CD
Community	Next	Your contributions, new MCP tools, more AI providers

🤝 Contributing

Contributions welcome! Read the contributing guide before opening a PR.

Good first contributions:

• New MCP tools for agents
• Additional AI provider adapters (Gemini, local models)
• Documentation improvements
• Accessibility and i18n

🧹 Maintenance Cadence

Sovra ships with automated maintenance reminders via GitHub Actions:

• Weekly health check: monitors latest CI, Security, Deploy runs and open security alert counts; opens an issue automatically if the repo is unhealthy.
• Monthly checklist: opens a recurring issue with a maintainer checklist for dependency reviews, security posture, and routine validation.

You can also run the cadence workflow manually from the Actions tab (Maintenance Cadence).

📜 License

MIT — use it for anything. Commercial, personal, educational. No strings.

---

_{Built by ByteWorthy
Ship AI products. Not infrastructure.}