gem-hunter
Language: TypeScript
Open-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.
AI-native, open-source backend-as-a-service.
Apache 2.0 · Self-hostable with Docker Compose · A Postgres database per app
Auth · Storage · Functions · Realtime · AI Gateway · RAG · MCP server
Website · Discord · LinkedIn · Self-host · Docs · Roadmap · Examples · Contributing
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.
docker compose -f docker-compose.local.yml up -d brings up the whole stack on your machine or your cloud; see Quickstart (self-host) and SETUP.md.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 for the 22 actions, Ask observation, retry keys and business memory. OSS-only MCP can run without the Office overlay.
Data
/schema), automatic REST endpoints (/auto-api), and migrations./rls)./v1/:app/kv/*). New in v0.2.0./storage).Compute
/functions)./durable-objects)./realtime)./edge-ssr, /edge-ssr-from-source)./frontend, /custom-domains).AI
agent-runtime (/agents; examples in Examples/agents/)./gateway, /ai-config)./rag)./integrations).Identity & ops
/auth, /oauth-config, /api-keys)./audit-logs)./webhooks).butterbase apps move; see docs/move-app.md).Agent surface
/mcp (HTTP) or via stdio (@butterbase/mcp — npx @butterbase/mcp).packages/plugin (submodule of butterbase-skills) ships 39 guided skills and 34 slash commands (idea → plan → schema → auth → functions → deploy → submit) for agentic app building.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 newapp_<id>you own, with its own database, URL, and API key. Thebutterbase clonepath requires an account at butterbase.ai. If you're self-hosting, thebackend/folder in each template contains the schema, RLS policies, and function code you would deploy manually against your own stack.
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
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
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:
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
butterbase clone app_0ycj4ad7odud my-support
cd my-supportVisit 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
This repo ships the runtime data plane — everything required to self-host a fully featured Butterbase instance. The managed offering at 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.
Requirements: Docker, Node 22+, npm.
The Claude Code plugin containing skills (packages/plugin) is a git submodule (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 butterbaseIf you already cloned without submodules:
git submodule update --init --recursive
Optional — keep submodules updated on every pull:
git config --global submodule.recurse truenpm 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).
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
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
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:devAuth 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
| 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.
┌──────────────────────────────────────────┐
│ 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:
db/control-plane/) — platform metadata: users, apps, billing, audit.db/runtime-plane/) — hot-path runtime tables (KV expose rules, realtime channels, sessions).db/data-plane/) — per-app user data; each app gets isolated schemas with RLS.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. |
@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.The OSS / managed boundary is intentional. The following are private to the managed offering:
If you need these for self-host, implement against the interfaces in packages/shared — see CONTRIBUTING.md for the scope rules.
SETUP.md — self-host and local development guideCHANGELOG.md — release notes (latest: v0.3.0, 2026-06-08 — Agents)ROADMAP.md — what's nextCONTRIBUTING.md — contributor workflow and OSS scopedocs/move-app.md — multi-region app movesExamples/ — small example apps (todo, grocery list)templates/ — full apps you can clone and run (butterSupport, butterbaseCRM)http://localhost:4321 after docker compose upLatest 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 for the full history.
See 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.
See SECURITY.md. Report vulnerabilities to security@butterbase.ai.
Apache-2.0. Copyright 2026 NetGPT Inc.