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.
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
Markdown
[](/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
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/appsLocal 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.
- ---
- name: butterbase
- description: AI-native, open-source backend-as-a-service with a built-in Model Context Protocol server. Postgres, auth, storage, functions, AI gateway.
- license: Apache-2.0
- category: mcp-servers
- supported_assistants:
- - claude-code
- - claude-desktop
- - cursor
- - windsurf
- - codex-cli
- homepage: https://butterbase.ai
- repository: https://github.com/butterbase-ai/butterbase
- mcp:
- npm_package: "@butterbase/mcp"
- hosted_endpoint: https://api.butterbase.ai/mcp
- transport: streamable-http
- registry: io.github.butterbase-ai/mcp
- ---
- # Butterbase
- **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.
- This repo ships the open-source runtime. The managed offering at [butterbase.ai](https://butterbase.ai) adds multi-region orchestration, billing, and ops.
- ## What the MCP server can do
- Nearly 40 tools across the platform's surface area, including:
- - **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`
- - **Schema** — `manage_schema` (declarative DSL, dry-run diffs), `manage_migrations`
- - **Auth** — `manage_auth_config`, `manage_auth_users`, `manage_oauth`
- - **Data** — `select_rows`, `insert_row`, `seed_database`
- - **Functions** — `deploy_function`, `invoke_function`, `manage_function`
- - **Storage** — `manage_storage` (presigned URLs, ACLs)
- - **Frontends** — `create_frontend_deployment`, `manage_frontend`, `manage_edge_ssr`
- - **RAG** — `manage_rag_content`, `rag_query`
- - **Realtime & Durable Objects** — `manage_realtime`, `manage_durable_objects`
- - **AI gateway** — `manage_ai` (chat, embeddings, BYOK)
- - **Row-Level Security** — `manage_rls`
- - **Integrations** — `manage_integrations` (Composio: email, Slack, GitHub, Notion, Linear, CRM)
- - **Billing** — `manage_billing` (Stripe Connect)
- - **KV, API keys, audit logs**, and more
- ## Install
- ### Option 1 — Claude Code plugin (recommended)
- ```bash
- claude plugin marketplace add https://github.com/butterbase-ai/butterbase-skills
- claude plugin install butterbase-skills@butterbase-skills
- ```
- Plugin includes 39 guided skills and 34 slash commands (`/butterbase-skills:journey`, `/butterbase-skills:build-app`, …) and auto-configures the MCP server.
- ### Option 2 — Hosted MCP (any client)
- Add to your MCP config:
- ```json
- {
- "mcpServers": {
- "butterbase": {
- "url": "https://api.butterbase.ai/mcp",
- "headers": {
- "Authorization": "Bearer ${BUTTERBASE_API_KEY}"
- }
- }
- }
- }
- ```
- ### Option 3 — Local stdio MCP
- ```bash
- npx @butterbase/mcp
- ```
- Or wire it up in your MCP config:
- ```json
- {
- "mcpServers": {
- "butterbase": {
- "command": "npx",
- "args": ["-y", "@butterbase/mcp"],
- "env": { "BUTTERBASE_API_KEY": "bb_sk_..." }
- }
- }
- }
- ```
- ### Option 4 — Self-host the whole stack
- See the [Quickstart](./README.md#quickstart-self-host) in `README.md`. Requires Docker + Node 22+.
- ## Get an API key
- Sign up at [butterbase.ai](https://butterbase.ai) and generate a key, or self-host and use the CLI:
- ```bash
- butterbase keys generate
- ```
- Keys are prefixed `bb_sk_…`.
- ## Supported AI assistants
- Any MCP-capable client works. Tested with: **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **Codex CLI**.
- ## Related
- - **[@butterbase/mcp](https://www.npmjs.com/package/@butterbase/mcp)** — stdio MCP server (this repo, installable from npm)
- - **[butterbase-skills](https://github.com/butterbase-ai/butterbase-skills)** — Claude Code plugin with 39 guided skills and 34 slash commands
- - **[@butterbase/sdk](https://www.npmjs.com/package/@butterbase/sdk)** — TypeScript SDK
- - **[@butterbase/cli](https://www.npmjs.com/package/@butterbase/cli)** — local dev / scaffolding CLI
- ## License
- Apache-2.0
- ## Optional video reference preparation
- 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.
- <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
- 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.
- **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>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.