Skip to content
Back to search

butterbase

AI-native, open-source backend-as-a-service with a built-in Model Context Protocol server. Postgres, auth, storage, functions, AI gateway.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/butterbase-ai/butterbase with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/butterbase-ai/butterbase'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/butterbase-ai--butterbase/badge.svg)](/listings/butterbase-ai--butterbase)

HTML

<a href="/listings/butterbase-ai--butterbase"><img src="/api/listings/butterbase-ai--butterbase/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**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.

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

If you already cloned without submodules:

git submodule update --init --recursive

Optional — keep submodules updated on every pull:

git config --global submodule.recurse true

2. Install dependencies and configure env

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.

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

Wait until control-api is healthy:

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):

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):

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`):

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)**.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 125 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: butterbase
  3. description: AI-native, open-source backend-as-a-service with a built-in Model Context Protocol server. Postgres, auth, storage, functions, AI gateway.
  4. license: Apache-2.0
  5. category: mcp-servers
  6. supported_assistants:
  7. - claude-code
  8. - claude-desktop
  9. - cursor
  10. - windsurf
  11. - codex-cli
  12. homepage: https://butterbase.ai
  13. repository: https://github.com/butterbase-ai/butterbase
  14. mcp:
  15. npm_package: "@butterbase/mcp"
  16. hosted_endpoint: https://api.butterbase.ai/mcp
  17. transport: streamable-http
  18. registry: io.github.butterbase-ai/mcp
  19. ---
  20. # Butterbase
  21. **AI-native, open-source backend-as-a-service** with a built-in Model Context Protocol (MCP) server. Postgres data plane, auth, storage, serverless functions, AI gateway, RAG, realtime, and durable objects — all drivable by an AI agent via MCP tools.
  22. This repo ships the open-source runtime. The managed offering at [butterbase.ai](https://butterbase.ai) adds multi-region orchestration, billing, and ops.
  23. ## What the MCP server can do
  24. Nearly 40 tools across the platform's surface area, including:
  25. - **Apps & regions** — `init_app`, `manage_app` (actions: list/delete/pause/get_config/update_access_mode/secure/update_cors/set_visibility/preview_clone_env_vars/clone/get_clone_job/find_templates/set_clone_webhook/link_substrate/unlink_substrate/move/move_status/teardown_source_replica), `list_regions`
  26. - **Schema** — `manage_schema` (declarative DSL, dry-run diffs), `manage_migrations`
  27. - **Auth** — `manage_auth_config`, `manage_auth_users`, `manage_oauth`
  28. - **Data** — `select_rows`, `insert_row`, `seed_database`
  29. - **Functions** — `deploy_function`, `invoke_function`, `manage_function`
  30. - **Storage** — `manage_storage` (presigned URLs, ACLs)
  31. - **Frontends** — `create_frontend_deployment`, `manage_frontend`, `manage_edge_ssr`
  32. - **RAG** — `manage_rag_content`, `rag_query`
  33. - **Realtime & Durable Objects** — `manage_realtime`, `manage_durable_objects`
  34. - **AI gateway** — `manage_ai` (chat, embeddings, BYOK)
  35. - **Row-Level Security** — `manage_rls`
  36. - **Integrations** — `manage_integrations` (Composio: email, Slack, GitHub, Notion, Linear, CRM)
  37. - **Billing** — `manage_billing` (Stripe Connect)
  38. - **KV, API keys, audit logs**, and more
  39. ## Install
  40. ### Option 1 — Claude Code plugin (recommended)
  41. ```bash
  42. claude plugin marketplace add https://github.com/butterbase-ai/butterbase-skills
  43. claude plugin install butterbase-skills@butterbase-skills
  44. ```
  45. Plugin includes 39 guided skills and 34 slash commands (`/butterbase-skills:journey`, `/butterbase-skills:build-app`, …) and auto-configures the MCP server.
  46. ### Option 2 — Hosted MCP (any client)
  47. Add to your MCP config:
  48. ```json
  49. {
  50. "mcpServers": {
  51. "butterbase": {
  52. "url": "https://api.butterbase.ai/mcp",
  53. "headers": {
  54. "Authorization": "Bearer ${BUTTERBASE_API_KEY}"
  55. }
  56. }
  57. }
  58. }
  59. ```
  60. ### Option 3 — Local stdio MCP
  61. ```bash
  62. npx @butterbase/mcp
  63. ```
  64. Or wire it up in your MCP config:
  65. ```json
  66. {
  67. "mcpServers": {
  68. "butterbase": {
  69. "command": "npx",
  70. "args": ["-y", "@butterbase/mcp"],
  71. "env": { "BUTTERBASE_API_KEY": "bb_sk_..." }
  72. }
  73. }
  74. }
  75. ```
  76. ### Option 4 — Self-host the whole stack
  77. See the [Quickstart](./README.md#quickstart-self-host) in `README.md`. Requires Docker + Node 22+.
  78. ## Get an API key
  79. Sign up at [butterbase.ai](https://butterbase.ai) and generate a key, or self-host and use the CLI:
  80. ```bash
  81. butterbase keys generate
  82. ```
  83. Keys are prefixed `bb_sk_…`.
  84. ## Supported AI assistants
  85. Any MCP-capable client works. Tested with: **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **Codex CLI**.
  86. ## Related
  87. - **[@butterbase/mcp](https://www.npmjs.com/package/@butterbase/mcp)** — stdio MCP server (this repo, installable from npm)
  88. - **[butterbase-skills](https://github.com/butterbase-ai/butterbase-skills)** — Claude Code plugin with 39 guided skills and 34 slash commands
  89. - **[@butterbase/sdk](https://www.npmjs.com/package/@butterbase/sdk)** — TypeScript SDK
  90. - **[@butterbase/cli](https://www.npmjs.com/package/@butterbase/cli)** — local dev / scaffolding CLI
  91. ## License
  92. Apache-2.0
  93. ## Optional video reference preparation
  94. For explicitly declared AI-generated fictional characters, follow [bundled AI command guidance](docs/plugin-ai-command.md). Use `reference_declarations` only when supplied or established by the caller, and choose `prepare_references: "on_rejection"` (default) or `"upfront"`. Keep the same job ID through preparation and settlement. Do not infer consent or retry an uncertain paid submission. Preparation sends image bytes to a provider for storage; explain the retention behavior in the linked guide.
README.md · README · 337 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src=".github/assets/logo.png" alt="Butterbase" width="420" />
  3. </p>
  4. <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>
  5. <p align="center">
  6. <a href="./LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg"></a>
  7. <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>
  8. <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>
  9. <br/>
  10. <a href="https://discord.gg/Aq7q5mqbrt"><img alt="Join Discord" src="https://img.shields.io/badge/Join-Discord-5865F2?logo=discord&logoColor=white"></a>
  11. <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>
  12. <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white">
  13. <img alt="Postgres" src="https://img.shields.io/badge/Postgres-336791?logo=postgresql&logoColor=white">
  14. <img alt="Docker" src="https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white">
  15. </p>
  16. <p align="center">
  17. <a href="https://butterbase.ai"><strong>Website</strong></a> ·
  18. <a href="https://discord.gg/Aq7q5mqbrt"><strong>Discord</strong></a> ·
  19. <a href="https://www.linkedin.com/company/butterbase/?trk=public_profile_following-company_profile-result-card_result-card_title"><strong>LinkedIn</strong></a> ·
  20. <a href="./SETUP.md"><strong>Self-host</strong></a> ·
  21. <a href="./docs"><strong>Docs</strong></a> ·
  22. <a href="./ROADMAP.md"><strong>Roadmap</strong></a> ·
  23. <a href="./Examples"><strong>Examples</strong></a> ·
  24. <a href="./CONTRIBUTING.md"><strong>Contributing</strong></a>
  25. </p>
  26. ---
  27. <!-- Drop a demo gif at .github/assets/demo.gif and uncomment:
  28. <p align="center"><img src=".github/assets/demo.gif" alt="Butterbase demo" width="720" /></p>
  29. -->
  30. 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.
  31. - **Open source, Apache 2.0.** The full runtime data plane is in this repo — no feature-gated "community edition".
  32. - **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).
  33. - **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.
  34. - **Or use the managed cloud.** [butterbase.ai](https://butterbase.ai) runs the same data plane multi-region, with a free tier to start.
  35. ## Features
  36. Managed-cloud Office clients are available through the optional `manage_office` MCP tool, `butterbase office` CLI commands and standalone SDK `OfficeClient`. They use an explicit organization and platform credential, with no app selection. Protected actions return a browser confirmation receipt for the initiating owner. Read [`butterbase_docs` topic `office`](https://docs.butterbase.ai/core-concepts/office-clients/) for the 44 actions, Ask observation, retry keys, curated memory, routine customization and paginated records. OSS-only MCP can run without the Office overlay.
  37. **Data**
  38. - **Postgres data plane** — per-app databases with declarative schema (`/schema`), automatic REST endpoints (`/auto-api`), and migrations.
  39. - **Row-Level Security** — first-class RLS policy management with user-isolation helpers (`/rls`).
  40. - **Key-Value store** — regional, quota-protected KV with TTL, audit trail, and dashboard expose rules (`/v1/:app/kv/*`). *New in v0.2.0.*
  41. - **File storage** — S3/R2-backed object storage with presigned URLs, ACLs, and async indexing (`/storage`).
  42. **Compute**
  43. - **Serverless functions** — TypeScript functions executed on the Deno runtime (`/functions`).
  44. - **Durable Objects** — stateful per-key actors for chat rooms, multiplayer, rate limiters, long-running agents (`/durable-objects`).
  45. - **Realtime** — WebSocket subscriptions to table changes for live UIs and presence (`/realtime`).
  46. - **Edge SSR** — deploy Next.js / Remix / Astro edge handlers from source (`/edge-ssr`, `/edge-ssr-from-source`).
  47. - **Frontend hosting** — zip or build-from-source static / SPA deploys with custom domains (`/frontend`, `/custom-domains`).
  48. **AI**
  49. - **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/`).
  50. - **AI gateway** — single endpoint for chat, embeddings, model listing; pluggable router adapters (`/gateway`, `/ai-config`).
  51. - **RAG** — managed collections, document ingestion, semantic search and synthesized answers (`/rag`).
  52. - **Integrations** — third-party tool access via Composio (`/integrations`).
  53. **Identity & ops**
  54. - **Auth** — email + OAuth (Google, GitHub, Apple, X, …), JWT tuning, post-login hooks, service keys (`/auth`, `/oauth-config`, `/api-keys`).
  55. - **Audit logs** — structured request audit trail across KV and other surfaces (`/audit-logs`).
  56. - **Webhooks** — outbound webhooks for app events (`/webhooks`).
  57. - **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)).
  58. **Agent surface**
  59. - **MCP server** — every capability above is exposed as MCP tools at `/mcp` (HTTP) or via stdio (`@butterbase/mcp` — `npx @butterbase/mcp`).
  60. - **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.
  61. ## Templates
  62. [`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.
  63. > **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.
  64. ### [`butterbaseCRM`](./templates/butterbaseCRM)
  65. 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.
  66. 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.
  67. **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
  68. ```bash
  69. butterbase clone app_44zjayftl7b3 butterbaseCRM
  70. cd butterbaseCRM
  71. cp frontend/.env.example frontend/.env.local # fill in your APP_ID
  72. cd frontend && npm install && npm run dev
  73. ```
  74. Full setup: [`templates/butterbaseCRM/QUICKSTART.md`](./templates/butterbaseCRM/QUICKSTART.md)
  75. ---
  76. ### [`butterSupport`](./templates/butterSupport)
  77. 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).
  78. It works in two depths from the same clone:
  79. - **Commodity tier** — paste a help-center URL, get a working agent in under 60 seconds. No product integration required.
  80. - **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).
  81. **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
  82. ```bash
  83. butterbase clone app_0ycj4ad7odud my-support
  84. cd my-support
  85. ```
  86. Visit your new subdomain, sign in with magic link, paste your help-center URL. Copy the embed snippet into your product HTML.
  87. Full setup: [`templates/butterSupport/README.md`](./templates/butterSupport/README.md)
  88. ---
  89. ## Open-source vs. managed
  90. 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).
  91. 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`.
  92. ## Quickstart (self-host)
  93. **Requirements:** Docker, Node 22+, npm.
  94. ### 1. Clone (with submodules)
  95. 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.
  96. ```bash
  97. git clone --recurse-submodules https://github.com/butterbase-ai/butterbase.git
  98. cd butterbase
  99. ```
  100. If you already cloned without submodules:
  101. ```bash
  102. git submodule update --init --recursive
  103. ```
  104. Optional — keep submodules updated on every pull:
  105. ```bash
  106. git config --global submodule.recurse true
  107. ```
  108. ### 2. Install dependencies and configure env
  109. ```bash
  110. npm ci
  111. cp .env.example .env
  112. ```
  113. `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`).
  114. ### 3. Start the stack
  115. First run builds images and can take several minutes.
  116. ```bash
  117. docker compose -f docker-compose.local.yml up -d
  118. ```
  119. Wait until control-api is healthy:
  120. ```bash
  121. curl -sf http://localhost:4000/health/ready
  122. ```
  123. ### 4. Run database migrations
  124. Schema is **not** applied automatically on container start. From the repo root (with the stack running):
  125. ```bash
  126. export NEON_PLATFORM_PRIMARY_URL=postgresql://butterbase:butterbase_dev@localhost:5433/butterbase_control
  127. export NEON_RUNTIME_PROJECT_ID_US_EAST_1=postgresql://butterbase:butterbase_dev@localhost:5437/butterbase_runtime_us
  128. export BUTTERBASE_REGIONS=us-east-1
  129. npm run migrate:all
  130. ```
  131. ### 5. Seed the local dev user
  132. With `AUTH_ENABLED=false`, the API uses `DEV_OWNER_ID` from compose. That user must exist in `platform_users` (fresh volumes start empty):
  133. ```bash
  134. export NEON_PLATFORM_PRIMARY_URL=postgresql://butterbase:butterbase_dev@localhost:5433/butterbase_control
  135. npm run seed:dev
  136. ```
  137. ### 6. Smoke test
  138. Auth is disabled in the local compose profile (`AUTH_ENABLED=false`):
  139. ```bash
  140. curl -X POST http://localhost:4000/init \
  141. -H "Content-Type: application/json" \
  142. -d '{"name": "my-app"}'
  143. curl http://localhost:4000/apps
  144. ```
  145. ### Local endpoints
  146. | Service | URL / port |
  147. |---------|------------|
  148. | Control API | http://localhost:4000 |
  149. | MCP (HTTP, via control-api) | http://localhost:4000/mcp |
  150. | Deno runtime | http://localhost:7133 |
  151. | Docs site | http://localhost:4321 |
  152. | Control plane Postgres | `localhost:5433` |
  153. | Data plane Postgres | `localhost:5435` |
  154. | Runtime plane Postgres | `localhost:5437` |
  155. | LocalStack (S3) | http://localhost:4566 |
  156. Full setup (auth, MCP clients, troubleshooting, production notes): **[`SETUP.md`](./SETUP.md)**.
  157. ## Architecture
  158. ```
  159. ┌──────────────────────────────────────────┐
  160. │ Your app · agent · MCP client · CLI │
  161. └──────────────────────┬───────────────────┘
  162. │ REST · WebSocket · MCP
  163. ┌──────────────────────▼───────────────────┐
  164. │ control-api (Fastify) │
  165. │ apps · auth · schema · auto-api · RLS │
  166. │ storage · functions · KV · realtime │
  167. │ AI gateway · RAG · DOs · MCP at /mcp │
  168. └──┬──────┬───────┬───────┬────────┬───────┘
  169. │ │ │ │ │
  170. ┌────────▼─┐ ┌──▼───┐ ┌─▼──┐ ┌──▼─────┐ ┌▼─────────────┐
  171. │ Postgres │ │ S3 / │ │Redis│ │ Deno │ │ Python agent │
  172. │ 3 planes │ │ R2 │ │ KV │ │runtime │ │ runtime │
  173. └──────────┘ └──────┘ └────┘ └────────┘ └──────────────┘
  174. ┌──────────────────┐
  175. │ Cloudflare: │
  176. │ build-runner · │
  177. │ dispatch-worker │
  178. └──────────────────┘
  179. ```
  180. **Three Postgres planes:**
  181. - **control-plane** (`db/control-plane/`) — platform metadata: users, apps, billing, audit.
  182. - **runtime-plane** (`db/runtime-plane/`) — hot-path runtime tables (KV expose rules, realtime channels, sessions).
  183. - **data-plane** (`db/data-plane/`) — per-app user data; each app gets isolated schemas with RLS.
  184. ## Repo layout
  185. **Services** (`services/`)
  186. | Service | Language | What it does |
  187. |---|---|---|
  188. | `control-api` | Node.js / Fastify | Main entry point. All public APIs, embeds MCP at `/mcp`. |
  189. | `mcp-server` | Node.js | MCP tool implementations (built into control-api; also ships as `butterbase-mcp` stdio binary). |
  190. | `deno-runtime` | Deno | Executes user serverless functions in isolates. |
  191. | `agent-runtime` | Python (uv) | Long-running agent executor for `manage_ai` / agent tasks. |
  192. | `build-runner` | Cloudflare Worker | Builds frontends and edge-SSR bundles from source. |
  193. | `do-invoker` | Cloudflare Worker | Lets non-Cloudflare services reach user Durable Objects. |
  194. | `storage-indexer` | Node.js | Async indexer for uploaded objects. |
  195. | `docs` | Astro | Public documentation site (also served locally at `:4321`). |
  196. **Packages** (`packages/`)
  197. | Package | Description |
  198. |---|---|
  199. | `@butterbase/sdk` | Universal TypeScript SDK (browser + server). |
  200. | `@butterbase/cli` | `butterbase` CLI for scaffolding and backend management. |
  201. | `@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). |
  202. | `@butterbase/shared` | Shared types, constants, and pluggable interfaces (`BillingProvider`, `QuotaEnforcer`, `RouterAdapter`). |
  203. | `@butterbase/static-frontend-worker` | Per-app static-frontend Cloudflare worker source (SPA fallback, `_redirects`); private, consumed by `control-api`. |
  204. **Other top-level pieces**
  205. - `dispatch-worker/` — Cloudflare Worker that routes per-app subdomain traffic.
  206. - `bb-placeholder/` — placeholder origin for unprovisioned subdomains.
  207. - `infra/` — `pgbouncer` and `traefik` configs for self-host.
  208. - `db/` — SQL migrations for the three Postgres planes.
  209. - `Examples/` — `todo-2026-04-02`, `grocery-list-2026-04-03`, `agents/`.
  210. - `templates/` — full production-shaped apps: `butterSupport`, `butterbaseCRM`.
  211. ## What's *not* in this repo
  212. The OSS / managed boundary is intentional. The following are private to the managed offering:
  213. - Multi-region orchestration and the cross-region scheduler.
  214. - Billing logic, lease-based quota math, and Stripe wire-up beyond the no-op provider.
  215. - Upstream AI router adapters (OpenAI / Anthropic / Bedrock provider integrations beyond the gateway interface).
  216. - Customer / admin dashboards, hackathon-host dashboards, and ops tooling.
  217. If you need these for self-host, implement against the interfaces in `packages/shared` — see [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the scope rules.
  218. ## Documentation
  219. - [`SETUP.md`](./SETUP.md) — self-host and local development guide
  220. - [`CHANGELOG.md`](./CHANGELOG.md) — release notes (latest: **v0.3.0**, 2026-06-08 — Agents)
  221. - [`ROADMAP.md`](./ROADMAP.md) — what's next
  222. - [`CONTRIBUTING.md`](./CONTRIBUTING.md) — contributor workflow and OSS scope
  223. - [`docs/move-app.md`](./docs/move-app.md) — multi-region app moves
  224. - [`Examples/`](./Examples) — small example apps (todo, grocery list)
  225. - [`templates/`](./templates) — full apps you can clone and run (butterSupport, butterbaseCRM)
  226. - Docs site (local): `http://localhost:4321` after `docker compose up`
  227. ## Project status
  228. 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.
  229. ## Community & support
  230. - **[Discord](https://discord.gg/Aq7q5mqbrt)** — chat with the team and other builders
  231. - **[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
  232. - **[GitHub Issues](https://github.com/butterbase-ai/butterbase/issues)** — bug reports, feature requests
  233. - **Email** — [yuki@butterbase.ai](mailto:yuki@butterbase.ai) for direct contact
  234. ## Contributing
  235. 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.
  236. ## Security
  237. See [`SECURITY.md`](./SECURITY.md). Report vulnerabilities to `security@butterbase.ai`.
  238. ## License
  239. [Apache-2.0](./LICENSE). Copyright 2026 NetGPT Inc.
  240. ## Contributors
  241. <a href="https://github.com/butterbase-ai/butterbase/graphs/contributors">
  242. <img src="https://contrib.rocks/image?repo=butterbase-ai/butterbase" alt="Contributors" />
  243. </a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.