Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.supaproxy.cloud/llms.txt

Use this file to discover all available pages before exploring further.

​
Philosophy

SupaProxy’s core is open source. The server, SDK, and plugin packages are available for self-hosting. SupaProxy Cloud (supaproxy.cloud) is a hosted version that adds multi-tenancy, billing, and managed infrastructure on top of the same codebase.

​
What’s the same

Cloud runs the exact same server and dashboard code as self-hosted. Every feature available in the open-source version is available on Cloud:
  • Workspaces, connections, consumers, knowledge sources
  • AI provider integration (Anthropic, OpenAI, any compatible provider)
  • MCP tool calling, conversation management, compliance guardrails
  • Full observability, conversation analysis, cost tracking
  • Plugin system for extending consumers, connections, providers

​
What Cloud adds

Cloud wraps the open-source server with a private overlay that adds:
FeatureOpen SourceCloud
TenancySingle org, single deploymentMulti-org, shared infrastructure
Data isolationEverything visible (your data)Org-scoped, cross-org access blocked
BillingSelf-managedSubscription plans, usage metering
InfrastructureYou manage servers, DB, RedisFully managed
AuthSingle org signup/loginMulti-org, invitations, SSO (planned)
ScalingYou handle itAuto-scaling, global CDN

​
How it works technically

The server exports composable building blocks via supaproxy-server/server:
  • createContainer(pool, options?). DI root with optional tenant service
  • createApp(container). Hono app with all routes
  • startConsumers(container). boot consumer plugins
  • startWorkers(container). boot lifecycle workers
The TenantService interface controls how workspaces are scoped and accessed: 
interface TenantService {
  scopeWorkspaceList(userOrgId: string): string | null
  verifyWorkspaceAccess(workspaceOrgId: string | null, userOrgId: string): void
  resolveOrgForCreation(userOrgId: string): string
}
Self-hosted: uses NoOpTenantService (no filtering, all access allowed, single-tenant). Cloud: an overlay imports the composable pieces, injects a multi-tenant TenantService, and mounts additional routes for billing, invitations, and org management. No server code is forked. The overlay wraps the server: 
import { createContainer, createApp, startConsumers, startWorkers } from 'supaproxy-server/server'

const container = createContainer(pool, { tenantService: myTenantService })
const app = createApp(container)
// add overlay-specific routes (billing, invitations, etc.)
app.route('/billing', billingRoutes)
startConsumers(container)
startWorkers(container)
The server code is identical. The runtime behavior differs based on which TenantService implementation is injected at startup and what additional routes the overlay mounts.

​
Repository structure

supaproxy-server        (open source)          ← Full product
overlay repo            (private)              ← Multi-tenancy, billing, managed infra
infra repo              (private)              ← Deployment configs
All plugin packages are open source: @supaproxy/sdk, @supaproxy/consumers, @supaproxy/connections, @supaproxy/knowledge-sources, @supaproxy/providers.

​
Contributing

Contributions to the open-source repos benefit both self-hosted and Cloud users. Cloud-specific features live in the private overlay and don’t affect the open-source product.