butterbase-oss

<p align="center"> <img src=".github/assets/logo.png" alt="Butterbase" width="420" /> </p> <p align="center"><strong>AI-native, open-source backend-as-a-service.</strong><br/>Apache 2.0 · Self-hostable with Docker Compose · A Postgres database per app<br/>Auth · Storage · Functions · Realtime · AI Gateway · RAG · MCP server</p> <p align="center"> <a href="./LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg"></a> <a href="https://github.com/butterbase-ai/butterbase/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/butterbase-ai/butterbase?style=social"></a> <a href="https://github.com/butterbase-ai/butterbase/network/members"><img alt="GitHub forks" src="https://img.shields.io/github/forks/butterbase-ai/butterbase?style=social"></a> <br/> <a href="https://discord.gg/Aq7q5mqbrt"><img alt="Join Discord" src="https://img.shields.io/badge/Join-Discord-5865F2?logo=discord&logoColor=white"></a> <a href="https://www.linkedin.com/company/butterbase/?trk=public_profile_following-company_profile-result-card_result-card_title"><img alt="Follow us on LinkedIn" src="https://img.shields.io/badge/Follow-LinkedIn-0A66C2?logo=linkedin&logoColor=white"></a> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white"> <img alt="Postgres" src="https://img.shields.io/badge/Postgres-336791?logo=postgresql&logoColor=white"> <img alt="Docker" src="https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white"> </p> <p align="center"> <a href="https://butterbase.ai"><strong>Website</strong></a> · <a href="https://discord.gg/Aq7q5mqbrt"><strong>Discord</strong></a> · <a href="https://www.linkedin.com/company/butterbase/?trk=public_profile_following-company_profile-result-card_result-card_title"><strong>LinkedIn</strong></a> · <a href="./SETUP.md"><strong>Self-host</strong></a> · <a href="./docs"><strong>Docs</strong></a> · <a href="./ROADMAP.md"><strong>Roadmap</strong></a> · <a href="./Examples"><strong>Examples</strong></a> · <a href="./CONTRIBUTING.md"><strong>Contributing</strong></a> </p> --- <!-- Drop a demo gif at .github/assets/demo.gif and uncomment: <p align="center"><img src=".github/assets/demo.gif" alt="Butterbase demo" width="720" /></p> --> 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-in **Model Context Protocol (MCP) server** so agents can operate your backend with tools instead of glue code. - **Open source, Apache 2.0.** The full runtime data plane is in this repo — no feature-gated "community edition". - **Self-host in one command.** `docker compose -f docker-compose.local.yml up -d` brings up the whole stack on your machine or your cloud; see [Quickstart (self-host)](#quickstart-self-host) and [`SETUP.md`](./SETUP.md). - **Real Postgres underneath.** Every app gets its own Postgres database with declarative schema, migrations, row-level security, and auto-generated REST. No proprietary datastore, no lock-in. - **Or use the managed cloud.** [butterbase.ai](https://butterbase.ai) runs the same data plane multi-region, with a free tier to start. ## Features **Data** - **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`). **Compute** - **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** - **Agents** — declarative multi-step LLM workflows (graph specs) with checkpointed runs, function/MCP tools, and human-approval pauses, executed by `agent-runtime` (`/agents`; examples in `Examples/agents/`). - **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`). **Identity & ops** - **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 (`butterbase apps move`; see [`docs/move-app.md`](./docs/move-app.md)). **Agent surface** - **MCP server** — every capability above is exposed as MCP tools at `/mcp` (HTTP) or via stdio (`@butterbase/mcp` — `npx @butterbase/mcp`). - **Claude Code plugin** — `packages/plugin` (submodule of [butterbase-skills](https://github.com/butterbase-ai/butterbase-skills)) ships 39 guided skills and 34 slash commands (idea → plan → schema → auth → functions → deploy → submit) for agentic app building. ## Templates [`templates/`](./templates) contains full, production-shaped applications built on Butterbase. These aren't starter skeletons — each one is a complete, running app with schema, RLS policies, deployed functions, auth config, and a React frontend. You clone the backend into your own Butterbase account and own a working product from day one. > **How cloning works:** `butterbase clone <app_id> <name>` is a managed-platform operation — it forks the live backend (schema, RLS, functions, auth/storage/realtime/AI configs) into a new `app_<id>` you own, with its own database, URL, and API key. The `butterbase clone` path requires an account at [butterbase.ai](https://butterbase.ai). If you're self-hosting, the `backend/` folder in each template contains the schema, RLS policies, and function code you would deploy manually against your own stack. ### [`butterbaseCRM`](./templates/butterbaseCRM) An open-source CRM for founders. Companies, people, deals (kanban), meetings, notes, and an activity feed — with Gmail and Google Calendar sync, company and person enrichment, email campaigns, multi-platform social publishing (X, LinkedIn, Reddit, TikTok), and a workspace AI agent that can query your CRM and propose actions for you to approve. Core CRM entities are stored as **substrate entities** — a cross-app, agent-readable memory layer — so other Butterbase apps you build (like butterSupport) share the same customer identity without any integration code between them. **What's included:** 29 Postgres tables · 56 serverless functions · Workspace AI agent (`agent-chat`) · Gmail + Calendar ingest via Composio · Enrichment (People Data Labs + Exa) · Social publishing via Composio · Realtime on 17 tables · Google OAuth + email auth · RLS on every table ```bash butterbase clone app_44zjayftl7b3 butterbaseCRM cd butterbaseCRM cp frontend/.env.example frontend/.env.local # fill in your APP_ID cd frontend && npm install && npm run dev ``` Full setup: [`templates/butterbaseCRM/QUICKSTART.md`](./templates/butterbaseCRM/QUICKSTART.md) --- ### [`butterSupport`](./templates/butterSupport) An AI support agent that diagnoses against your real product data, not just your help-center docs. A per-ticket Durable Object agent loop reads live customer state from substrate (failed payments, auth errors, account tier), drafts a reply, and posts it for founder approval before anything reaches the customer. Ships with an embeddable widget and a founder console (inbox, live reasoning stream, approval flow). It works in two depths from the same clone: - **Commodity tier** — paste a help-center URL, get a working agent in under 60 seconds. No product integration required. - **Deep tier** — link your main product app so the agent reads live substrate signals and can propose governed actions (resend verification, retry webhook, flag bug, apply credit). **What's included:** 20 Postgres tables · 30 serverless functions · 2 Durable Objects (`SupportTicketDO`, `WidgetTicketDO`) · RAG collection over your help center · Embeddable widget (53KB gzipped) · HMAC-signed user identity · Founder approval on every customer-visible reply · Escalation to Slack or Gmail via Composio ```bash butterbase clone app_0ycj4ad7odud my-support cd my-support ``` Visit your new subdomain, sign in with magic link, paste your help-center URL. Copy the embed snippet into your product HTML. Full setup: [`templates/butterSupport/README.md`](./templates/butterSupport/README.md) --- ## Open-source vs. managed This repo ships the **runtime data plane** — everything required to self-host a fully featured Butterbase instance. The **managed offering** at [butterbase.ai](https://butterbase.ai) adds multi-region orchestration, billing, upstream AI router adapters, lease-based quota enforcement, and ops dashboards (those live in a private repo that consumes this one as a submodule). 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 the `BillingProvider`, `QuotaEnforcer`, and `RouterAdapter` interfaces in `packages/shared`. ## Quickstart (self-host) **Requirements:** Docker, Node 22+, npm. ### 1. Clone (with submodules) The Claude Code plugin containing skills (`packages/plugin`) is a git submodule ([butterbase-skills](https://github.com/butterbase-ai/butterbase-skills)). A plain clone leaves `packages/plugin/` empty and `npm install` silently skips that workspace. ```bash git clone --recurse-submodules https://github.com/butterbase-ai/butterbase.git cd butterbase ``` If you already cloned without submodules: ```bash git submodule update --init --recursive ``` Optional — keep submodules updated on every pull: ```bash git config --global submodule.recurse true ``` ### 2. Install dependencies and configure env ```bash npm ci cp .env.example .env ``` `docker-compose.local.yml` sets `KV_REDIS_URL_US_EAST_1` for you. Edit `.env` only if you override defaults (e.g. run control-api on the host — use `redis://localhost:6379`). ### 3. Start the stack First run builds images and can take several minutes. ```bash docker compose -f docker-compose.local.yml up -d ``` Wait until control-api is healthy: ```bash curl -sf http://localhost:4000/health/ready ``` ### 4. Run database migrations Schema is **not** applied automatically on container start. From the repo root (with the stack running): ```bash 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 ``` ### 5. Seed the local dev user With `AUTH_ENABLED=false`, the API uses `DEV_OWNER_ID` from compose. That user must exist in `platform_users` (fresh volumes start empty): ```bash export NEON_PLATFORM_PRIMARY_URL=postgresql://butterbase:butterbase_dev@localhost:5433/butterbase_control npm run seed:dev ``` ### 6. Smoke test Auth is disabled in the local compose profile (`AUTH_ENABLED=false`): ```bash curl -X POST http://localhost:4000/init \ -H "Content-Type: application/json" \ -d '{"name": "my-app"}' curl http://localhost:4000/apps ``` ### Local endpoints | Service | URL / port | |---------|------------| | Control API | http://localhost:4000 | | MCP (HTTP, via control-api) | http://localhost:4000/mcp | | Deno runtime | http://localhost:7133 | | Docs site | http://localhost:4321 | | Control plane Postgres | `localhost:5433` | | Data plane Postgres | `localhost:5435` | | Runtime plane Postgres | `localhost:5437` | | LocalStack (S3) | http://localhost:4566 | Full setup (auth, MCP clients, troubleshooting, production notes): **[`SETUP.md`](./SETUP.md)**. ## Architecture ``` ┌──────────────────────────────────────────┐ │ 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 │ └──────────────────┘ ``` **Three Postgres planes:** - **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. ## Repo layout **Services** (`services/`) | Service | Language | What it does | |---|---|---| | `control-api` | Node.js / Fastify | Main entry point. All public APIs, embeds MCP at `/mcp`. | | `mcp-server` | Node.js | MCP tool implementations (built into control-api; also ships as `butterbase-mcp` stdio binary). | | `deno-runtime` | Deno | Executes user serverless functions in isolates. | | `agent-runtime` | Python (uv) | Long-running agent executor for `manage_ai` / agent tasks. | | `build-runner` | Cloudflare Worker | Builds frontends and edge-SSR bundles from source. | | `do-invoker` | Cloudflare Worker | Lets non-Cloudflare services reach user Durable Objects. | | `storage-indexer` | Node.js | Async indexer for uploaded objects. | | `docs` | Astro | Public documentation site (also served locally at `:4321`). | **Packages** (`packages/`) | Package | Description | |---|---| | `@butterbase/sdk` | Universal TypeScript SDK (browser + server). | | `@butterbase/cli` | `butterbase` CLI for scaffolding and backend management. | | `@butterbase/skills` | Claude Code plugin — 39 guided skills and 34 slash commands for AI-driven app building. Git submodule of [butterbase-skills](https://github.com/butterbase-ai/butterbase-skills). | | `@butterbase/shared` | Shared types, constants, and pluggable interfaces (`BillingProvider`, `QuotaEnforcer`, `RouterAdapter`). | | `@butterbase/static-frontend-worker` | Per-app static-frontend Cloudflare worker source (SPA fallback, `_redirects`); private, consumed by `control-api`. | **Other top-level pieces** - `dispatch-worker/` — Cloudflare Worker that routes per-app subdomain traffic. - `bb-placeholder/` — placeholder origin for unprovisioned subdomains. - `infra/` — `pgbouncer` and `traefik` configs for self-host. - `db/` — SQL migrations for the three Postgres planes. - `Examples/` — `todo-2026-04-02`, `grocery-list-2026-04-03`, `agents/`. - `templates/` — full production-shaped apps: `butterSupport`, `butterbaseCRM`. ## What's *not* in this repo 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. If you need these for self-host, implement against the interfaces in `packages/shared` — see [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the scope rules. ## Documentation - [`SETUP.md`](./SETUP.md) — self-host and local development guide - [`CHANGELOG.md`](./CHANGELOG.md) — release notes (latest: **v0.3.0**, 2026-06-08 — Agents) - [`ROADMAP.md`](./ROADMAP.md) — what's next - [`CONTRIBUTING.md`](./CONTRIBUTING.md) — contributor workflow and OSS scope - [`docs/move-app.md`](./docs/move-app.md) — multi-region app moves - [`Examples/`](./Examples) — small example apps (todo, grocery list) - [`templates/`](./templates) — full apps you can clone and run (butterSupport, butterbaseCRM) - Docs site (local): `http://localhost:4321` after `docker compose up` ## Project status Latest release: **v0.3.0** (2026-06-08) — adds Agents (graph-spec LLM workflows, function-as-agent-tool, multi-trigger functions); v0.2.0 added the KV store across SDK / REST / CLI / MCP. The data plane is production-tested by the managed offering; the OSS distribution is young — please file self-host issues and we'll tighten docs and defaults from feedback. See [`CHANGELOG.md`](./CHANGELOG.md) for the full history. ## Community & support - **[Discord](https://discord.gg/Aq7q5mqbrt)** — chat with the team and other builders - **[LinkedIn](https://www.linkedin.com/company/butterbase/?trk=public_profile_following-company_profile-result-card_result-card_title)** — follow us for product updates and announcements - **[GitHub Issues](https://github.com/butterbase-ai/butterbase/issues)** — bug reports, feature requests - **Email** — [yuki@butterbase.ai](mailto:yuki@butterbase.ai) for direct contact ## Contributing See [`CONTRIBUTING.md`](./CONTRIBUTING.md). The boundary between OSS and the managed offering is intentional — please read the scope section before opening a PR that touches billing, quota math, or upstream router adapters. ## Security See [`SECURITY.md`](./SECURITY.md). Report vulnerabilities to `security@butterbase.ai`. ## License [Apache-2.0](./LICENSE). Copyright 2026 NetGPT Inc. ## Contributors <a href="https://github.com/butterbase-ai/butterbase/graphs/contributors"> <img src="https://contrib.rocks/image?repo=butterbase-ai/butterbase" alt="Contributors" /> </a>