Butterbase: An AI-Native Open-Source Backend Stack

What Butterbase Packages into One Platform

Butterbase addresses a specific problem: developers building AI applications typically assemble five or more separate infrastructure services before writing any application code. They need a database with access control, a file store, a functions runtime, an authentication layer, a way to call language models, and now increasingly an interface for AI agents. Butterbase ships all of these as a single open-source platform under an Apache-2.0 license.

The target audience is developers or small teams shipping AI-native products. The README describes it as "AI-native" rather than adding AI as an afterthought: the AI gateway, RAG pipeline, and MCP server are core primitives, not optional add-ons installed later.

The project is at version 0.1.0 with no published GitHub releases. The last push was on 2026-09-27. The repository includes a ROADMAP.md and CHANGELOG.md, but the absence of release tags signals early-stage development.

The Data Layer: Postgres, KV Store, and File Storage

The data foundation is a per-app Postgres database with a declarative schema under the `/schema` directory, automatic REST endpoints under `/auto-api`, and migration support. Row-level security is treated as a core concern: the platform provides RLS policy management with user-isolation helpers in `/rls`, allowing applications to enforce per-user data boundaries at the database level without custom middleware.

A key-value store, introduced in v0.2.0, provides regional, quota-protected KV with TTL support and an audit trail, accessible at `/v1/:app/kv/*`. File storage is backed by S3 or Cloudflare R2, with presigned URLs, access control lists, and asynchronous indexing under `/storage`.

The combination of structured data in Postgres, short-lived state in the KV store, and binary objects in file storage covers the three main persistence patterns for AI applications without requiring separate services to be provisioned and configured.

Compute: Functions, Durable Actors, and Realtime Subscriptions

Serverless functions run on the Deno runtime and are managed under `/functions`. The choice of Deno rather than Node.js means TypeScript is the intended language and Node.js-specific modules may need compatibility layers.

Durable Objects, listed under `/durable-objects`, are stateful per-key actors. The README names their intended use cases: chat rooms, multiplayer sessions, rate limiters, and long-running agents. Each Durable Object is keyed, so a per-ticket or per-session agent holds its own state independently from others.

Realtime WebSocket subscriptions to table changes are available under `/realtime` for live user interfaces and presence indicators. The platform also handles edge server-side rendering for Next.js, Remix, and Astro via `/edge-ssr`, and static or single-page-app frontend hosting with custom domain support under `/frontend`.

The AI Gateway and RAG Pipeline

The AI gateway at `/gateway` provides a single endpoint for chat completions, embeddings, and model listing. It uses pluggable router adapters, meaning the underlying model provider can be swapped via `/ai-config` without changing application code. This centralizes model access rather than scattering provider credentials across individual services.

Above the gateway sits the RAG system under `/rag`, which manages document collections, handles document ingestion, and supports semantic search and synthesized answer generation. Third-party tool integrations are available through Composio under `/integrations`, covering external services like Gmail and Google Calendar, as used by the butterbaseCRM template.

Having the vector search pipeline and the generation endpoint in the same platform as the application database removes a common integration step, but it also means that switching providers at the RAG layer requires understanding the platform's internal configuration rather than just swapping a client library. The README does not document which model providers are supported by the gateway adapters by default.

Getting Started with Templates

The `templates/` directory holds complete, production-shaped applications built on Butterbase. The butterbaseCRM template includes 29 Postgres tables, 55 or more serverless functions, Gmail and Google Calendar sync via Composio, contact enrichment through People Data Labs and Exa, social publishing to multiple platforms, and a workspace AI agent.

Cloning a template on the managed platform uses the `butterbase clone` command:

butterbase clone app_44zjayftl7b3 butterbaseCRM
cd butterbaseCRM
cp frontend/.env.example frontend/.env.local
cd frontend && npm install && npm run dev

This forks the live backend into a new app you own, with its own database, URL, and API key. The `.env.local` file requires your `APP_ID` to connect the frontend to your new backend instance.

The butterSupport template provides an AI support agent built on a Durable Object called `SupportTicketDO`. It works in two modes: a commodity tier where pasting a help-center URL yields a working agent within 60 seconds, and a deep tier where the agent reads live product data from the substrate layer to draft replies.

For self-hosting, each template's `backend/` folder contains the schema, RLS policies, and function code to deploy manually. The `butterbase clone` path requires an account at butterbase.ai; the SETUP.md file documents the self-hosting alternative.

The MCP Server and the Agent Surface

Every Butterbase capability is exposed as Model Context Protocol tools. The MCP server runs at `/mcp` over HTTP or via standard I/O through the `@butterbase/mcp` npm package:

npx @butterbase/mcp

An agent supporting MCP can call database queries, read or write KV entries, trigger serverless functions, manage files, and access the AI gateway without custom API clients. This is the architectural feature that separates Butterbase from general-purpose BaaS platforms, which typically require developers to write agent-facing APIs by hand.

The repository also ships a Claude Code plugin under `packages/plugin` as a submodule of the butterbase-skills repository. The plugin provides 30 or more guided skills covering the workflow from initial idea through schema design, auth configuration, function deployment, and submission. These skills run inside Claude Code's agentic sessions.

The audit log surface under `/audit-logs` records requests across the KV store and other services. Outbound webhooks for application events are managed under `/webhooks`.

Limitations and Where Butterbase Is Not the Right Fit

Version 0.1.0 with no release tags means the public API can change without a migration guide. Applications built against Butterbase today are taking on the risk of breaking changes before a stable release. The project has a CHANGELOG.md and a ROADMAP.md, but neither substitutes for a versioning commitment.

The managed template clone requires an account at butterbase.ai, tying that workflow to an external hosted platform. The self-hosting documentation in SETUP.md exists, but the `.env.example` file shows that a production multi-region deployment requires separate Neon database project IDs, Fly.io app names, and a Redis URL, which must be provisioned independently.

The Durable Objects model for per-session agents is a specific design choice. If your workload needs global state shared across many agents rather than isolated per-key actors, you would need to build that coordination layer on top of the KV store or database.

Supabase is a well-established alternative that provides Postgres, row-level security, auth, file storage, and realtime subscriptions under a stable, widely-used API. Supabase does not include a built-in AI gateway, a first-class RAG pipeline as a core primitive, or a platform-level MCP server. Teams that do not need the integrated AI layer will find Supabase's longer track record and larger ecosystem easier to evaluate.

Editorial conclusion

Butterbase is a practical choice for developers who want all the infrastructure primitives for an AI application in one place and can accept a platform still at version 0.1.0 with no stable release tags. Teams that need a long-tested, production-hardened stack should wait. Before adopting, verify that your deployment target is covered by the SETUP.md self-hosting guide and that your toolchain runs on Node.js 22 or later.

Frequently asked questions

Official sources

1. butterbase-ai/butterbase on GitHub
2. Issues
3. License: Apache-2.0
4. README