Butterbase

Butterbase gives you the building blocks for AI-driven applications without lock-in: a Postgres-backed backend with row-level security, serverless functions, an LLM gateway, realtime subscriptions, key-value store, file storage, RAG, durable per-key actors, and a built-inModel Context Protocol (MCP) serverso agents can operate your backend with tools instead of glue code.

- Postgres data plane— per-app databases with declarative schema (/schema), automatic REST endpoints (/auto-api), and migrations.
- Row-Level Security— first-class RLS policy management with user-isolation helpers (/rls).
- Key-Value store— regional, quota-protected KV with TTL, audit trail, and dashboard expose rules (/v1/:app/kv/).New in v0.2.0.*
- File storage— S3/R2-backed object storage with presigned URLs, ACLs, and async indexing (/storage).

- Serverless functions— TypeScript functions executed on the Deno runtime (/functions).
- Durable Objects— stateful per-key actors for chat rooms, multiplayer, rate limiters, long-running agents (/durable-objects).
- Realtime— WebSocket subscriptions to table changes for live UIs and presence (/realtime).
- Edge SSR— deploy Next.js / Remix / Astro edge handlers from source (/edge-ssr,/edge-ssr-from-source).
- Frontend hosting— zip or build-from-source static / SPA deploys with custom domains (/frontend,/custom-domains).

- AI gateway— single endpoint for chat, embeddings, model listing; pluggable router adapters (/gateway,/ai-config).
- RAG— managed collections, document ingestion, semantic search and synthesized answers (/rag).
- Integrations— third-party tool access via Composio (/integrations).

- Auth— email + OAuth (Google, GitHub, Apple, X, …), JWT tuning, post-login hooks, service keys (/auth,/oauth-config,/api-keys).
- Audit logs— structured request audit trail across KV and other surfaces (/audit-logs).
- Webhooks— outbound webhooks for app events (/webhooks).
- Multi-region app moves— relocate an app across regions with retained source replicas (scripts/move-app/).

When you self-host, the AI gateway runs without upstream router adapters, billing uses a no-op provider, and quotas are unlimited. Wire your own implementations via theBillingProvider,QuotaEnforcer, andRouterAdapterinterfaces inpackages/shared.

git clone --recurse-submodules https://github.com/butterbase-ai/butterbase.git cd butterbase

If you already cloned without submodules:

Optional — keep submodules updated on every pull:

git config --global submodule.recurse true

2. Install dependencies and configure env

docker-compose.local.ymlsetsKV_REDIS_URL_US_EAST_1for you. Edit.envonly if you override defaults (e.g. run control-api on the host — useredis://localhost:6379).

First run builds images and can take several minutes.

docker compose -f docker-compose.local.yml up -d

curl -sf http://localhost:4000/health/ready

Schema isnotapplied automatically on container start. From the repo root (with the stack running):

export NEON_PLATFORM_PRIMARY_URL=postgresql://butterbase:butterbase_dev@localhost:5433/butterbase_control export NEON_RUNTIME_PROJECT_ID_US_EAST_1=postgresql://butterbase:butterbase_dev@localhost:5437/butterbase_runtime_us export BUTTERBASE_REGIONS=us-east-1 npm run migrate:all

WithAUTH_ENABLED=false, the API usesDEV_OWNER_IDfrom compose. That user must exist inplatform_users(fresh volumes start empty):

export NEON_PLATFORM_PRIMARY_URL=postgresql://butterbase:butterbase_dev@localhost:5433/butterbase_control npm run seed:dev

Auth is disabled in the local compose profile (AUTH_ENABLED=false):

curl -X POST http://localhost:4000/init \ -H "Content-Type: application/json" \ -d '{"name": "my-app"}' curl http://localhost:4000/apps

┌──────────────────────────────────────────┐ │ Your app · agent · MCP client · CLI │ └──────────────────────┬───────────────────┘ │ REST · WebSocket · MCP ┌──────────────────────▼───────────────────┐ │ control-api (Fastify) │ │ apps · auth · schema · auto-api · RLS │ │ storage · functions · KV · realtime │ │ AI gateway · RAG · DOs · MCP at /mcp │ └──┬──────┬───────┬───────┬────────┬───────┘ │ │ │ │ │ ┌────────▼─┐ ┌──▼───┐ ┌─▼──┐ ┌──▼─────┐ ┌▼─────────────┐ │ Postgres │ │ S3 / │ │Redis│ │ Deno │ │ Python agent │ │ 3 planes │ │ R2 │ │ KV │ │runtime │ │ runtime │ └──────────┘ └──────┘ └────┘ └────────┘ └──────────────┘ ┌──────────────────┐ │ Cloudflare: │ │ build-runner · │ │ dispatch-worker │ └──────────────────┘

- control-plane(db/control-plane/) — platform metadata: users, apps, billing, audit.
- runtime-plane(db/runtime-plane/) — hot-path runtime tables (KV expose rules, realtime channels, sessions).
- data-plane(db/data-plane/) — per-app user data; each app gets isolated schemas with RLS.

- dispatch-worker/— Cloudflare Worker that routes per-app subdomain traffic.
- bb-placeholder/— placeholder origin for unprovisioned subdomains.
- infra/—pgbouncerandtraefikconfigs for self-host.
- db/— SQL migrations for the three Postgres planes.
- Examples/—todo-2026-04-02,grocery-list-2026-04-03.

The OSS / managed boundary is intentional. The following are private to the managed offering:

- Multi-region orchestration and the cross-region scheduler.
- Billing logic, lease-based quota math, and Stripe wire-up beyond the no-op provider.
- Upstream AI router adapters (OpenAI / Anthropic / Bedrock provider integrations beyond the gateway interface).
- Customer / admin dashboards, hackathon-host dashboards, and ops tooling.

Go from AI prompt to live app in one click. CloudBase AI ToolKit is the bridge that connects your AI IDE (Cursor, Copilot, etc.) directly to Tencent CloudBase.

Introspect and query your apps deployed to Convex.

A template for deploying a remote, authentication-free MCP server on Cloudflare Workers. Tools are defined directly in the source code.

Integrate with the Codehooks.io serverless backend platform.

Integrate with the Coolify API to manage your servers, applications, and databases.

Deploy production backends, APIs, cron jobs and automations from any AI assistant. Database, auth, storage and 24+ integrations included.

Deploy Python functions as web apps. Type hints become UI, API, and shareable links. 32 MCP tools for deploy, run, storage, secrets, scheduling, versioning, and sharing.

A template for deploying a remote MCP server on Cloudflare Workers without authentication.

Interact with the Neon serverless Postgres platform