Butterbase

Plataforma de backend full-stack MCP — provisione aplicativos, gerencie bancos de dados, implante funções e muito mais.

Documentação

Backend-como-serviço de código aberto, nativo para IA.
Postgres · Auth · Storage · Functions · AI Gateway · Servidor MCP

Website · Discord · LinkedIn · Self-host · Docs · Roadmap · Examples · Contributing

O Butterbase oferece os blocos de construção para aplicações orientadas por IA sem lock-in: um backend baseado em Postgres com segurança em nível de linha, funções serverless, um gateway de LLM, assinaturas em tempo real, armazenamento chave-valor, armazenamento de arquivos, RAG, atores duráveis por chave e um servidor Model Context Protocol (MCP) integrado, para que agentes possam operar seu backend com ferramentas em vez de código de cola.

Recursos

Dados

Plano de dados Postgres — bancos de dados por aplicação com schema declarativo (/schema), endpoints REST automáticos (/auto-api) e migrações.
Segurança em nível de linha — gerenciamento de políticas RLS de primeira classe com auxiliares de isolamento de usuário (/rls).
Armazenamento chave-valor — KV regional com proteção de cota, TTL, trilha de auditoria e regras de exposição no dashboard (/v1/:app/kv/*). Novo na v0.2.0.
Armazenamento de arquivos — armazenamento de objetos com suporte a S3/R2, URLs pré-assinadas, ACLs e indexação assíncrona (/storage).

Computação

Funções serverless — funções TypeScript executadas no runtime Deno (/functions).
Objetos duráveis — atores com estado por chave para salas de chat, multiplayer, limitadores de taxa e agentes de longa duração (/durable-objects).
Tempo real — assinaturas WebSocket para mudanças em tabelas, para UIs ao vivo e presença (/realtime).
SSR de borda — implante handlers de borda Next.js / Remix / Astro a partir do código-fonte (/edge-ssr, /edge-ssr-from-source).
Hospedagem de frontend — deploys estáticos / SPA via zip ou build a partir do código-fonte, com domínios personalizados (/frontend, /custom-domains).

Gateway de IA — endpoint único para chat, embeddings e listagem de modelos; adaptadores de roteador plugáveis (/gateway, /ai-config).
RAG — coleções gerenciadas, ingestão de documentos, busca semântica e respostas sintetizadas (/rag).
Integrações — acesso a ferramentas de terceiros via Composio (/integrations).

Identidade e operações

Auth — e-mail + OAuth (Google, GitHub, Apple, X, …), ajuste de JWT, hooks pós-login e chaves de serviço (/auth, /oauth-config, /api-keys).
Logs de auditoria — trilha de auditoria estruturada de requisições em KV e outras superfícies (/audit-logs).
Webhooks — webhooks de saída para eventos de aplicação (/webhooks).
Movimentação multi-região de apps — realoque uma aplicação entre regiões mantendo réplicas de origem (scripts/move-app/).

Superfície de agentes

Servidor MCP — todos os recursos acima são expostos como ferramentas MCP em /mcp (HTTP) ou via stdio (@butterbase/mcp — npx @butterbase/mcp).
Plugin Claude Code — packages/plugin (submódulo de butterbase-skills) inclui mais de 30 skills guiadas (ideia → plano → schema → auth → funções → deploy → envio) para construção de aplicações orientadas por agentes.

Open-source vs. gerenciado

Este repositório entrega o plano de dados de runtime — tudo o que é necessário para auto-hospedar uma instância completa do Butterbase. A oferta gerenciada em butterbase.ai adiciona orquestração multi-região, cobrança, adaptadores de roteador de IA upstream, aplicação de cotas baseadas em lease e dashboards de operações (esses vivem em um repositório privado que consome este como submódulo).

Quando você auto-hospeda, o gateway de IA roda sem adaptadores de roteador upstream, a cobrança usa um provedor no-op e as cotas são ilimitadas. Conecte suas próprias implementações via as interfaces BillingProvider, QuotaEnforcer e RouterAdapter em packages/shared.

Início rápido (self-host)

Requisitos: Docker, Node 22+, npm.

1. Clone (com submódulos)

O plugin Claude Code contendo as skills (packages/plugin) é um submódulo git (butterbase-skills). Um clone simples deixa packages/plugin/ vazio e npm install pula silenciosamente esse workspace.

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

Se você já clonou sem submódulos:

git submodule update --init --recursive

Opcional — mantenha os submódulos atualizados a cada pull:

git config --global submodule.recurse true

2. Instale as dependências e configure o env

npm ci
cp .env.example .env

docker-compose.local.yml define KV_REDIS_URL_US_EAST_1 para você. Edite .env apenas se você sobrescrever os padrões (por exemplo, rodar a control-api no host — use redis://localhost:6379).

3. Inicie a stack

A primeira execução compila as imagens e pode levar vários minutos.

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

Aguarde até que a control-api esteja saudável:

curl -sf http://localhost:4000/health/ready

4. Execute as migrações do banco de dados

O schema não é aplicado automaticamente na inicialização do contêiner. A partir da raiz do repositório (com a stack em execução):

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. Semeie o usuário dev local

Com AUTH_ENABLED=false, a API usa DEV_OWNER_ID do compose. Esse usuário deve existir em platform_users (volumes novos começam vazios):

export NEON_PLATFORM_PRIMARY_URL=postgresql://butterbase:butterbase_dev@localhost:5433/butterbase_control
npm run seed:dev

6. Teste de fumaça

A autenticação está desabilitada no perfil local do compose (AUTH_ENABLED=false):

curl -X POST http://localhost:4000/init \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

curl http://localhost:4000/apps

Endpoints locais

Serviço	URL / porta
Control API	http://localhost:4000
MCP (HTTP, via control-api)	http://localhost:4000/mcp
Runtime Deno	http://localhost:7133
Site de documentação	http://localhost:4321
Postgres do plano de controle	`localhost:5433`
Postgres do plano de dados	`localhost:5435`
Postgres do plano de runtime	`localhost:5437`
LocalStack (S3)	http://localhost:4566

Configuração completa (auth, clientes MCP, solução de problemas, notas de produção): SETUP.md.

Arquitetura

              ┌──────────────────────────────────────────┐
              │    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  │
                                              └──────────────────┘

Três planos Postgres:

plano de controle (db/control-plane/) — metadados da plataforma: usuários, aplicações, cobrança, auditoria.
plano de runtime (db/runtime-plane/) — tabelas de runtime de caminho quente (regras de exposição KV, canais em tempo real, sessões).
plano de dados (db/data-plane/) — dados de usuário por aplicação; cada aplicação recebe schemas isolados com RLS.

Estrutura do repositório

Serviços (services/)

Serviço	Linguagem	O que faz
`control-api`	Node.js / Fastify	Ponto de entrada principal. Todas as APIs públicas, incorpora MCP em `/mcp`.
`mcp-server`	Node.js	Implementações de ferramentas MCP (integradas à control-api; também é distribuído como binário stdio `butterbase-mcp`).
`deno-runtime`	Deno	Executa funções serverless do usuário em isolates.
`agent-runtime`	Python (uv)	Executor de agentes de longa duração para `manage_ai` / tarefas de agente.
`build-runner`	Cloudflare Worker	Compila frontends e bundles edge-SSR a partir do código-fonte.
`storage-indexer`	Node.js	Indexador assíncrono para objetos enviados.
`docs`	Astro	Site público de documentação (também servido localmente em `:4321`).

Pacotes (packages/)

Pacote	Descrição
`@butterbase/sdk`	SDK TypeScript universal (navegador + servidor).
`@butterbase/cli`	CLI `butterbase` para scaffolding e gerenciamento de backend.
`@butterbase/plugin`	Plugin Claude Code — mais de 30 skills guiadas para construção de aplicações orientadas por IA. Submódulo git de butterbase-skills.
`@butterbase/shared`	Tipos compartilhados, constantes e interfaces plugáveis (`BillingProvider`, `QuotaEnforcer`, `RouterAdapter`).

Outras peças de nível superior

dispatch-worker/ — Cloudflare Worker que roteia tráfego de subdomínios por aplicação.
bb-placeholder/ — origem de placeholder para subdomínios não provisionados.
infra/ — configs pgbouncer e traefik para self-host.
db/ — migrações SQL para os três planos Postgres.
Examples/ — todo-2026-04-02, grocery-list-2026-04-03.
templates/ — aplicações completas com formato de produção: butterSupport, butterbaseCRM.

O que não está neste repositório

A fronteira OSS / gerenciado é intencional. Os itens a seguir são privados da oferta gerenciada:

Orquestração multi-região e o agendador entre regiões.
Lógica de cobrança, matemática de cotas baseadas em lease e integração com Stripe além do provedor no-op.
Adaptadores de roteador de IA upstream (integrações de provedores OpenAI / Anthropic / Bedrock além da interface do gateway).
Dashboards de clientes / administradores, dashboards de hosts de hackathon e ferramentas de operações.

Se você precisar desses itens para self-host, implemente contra as interfaces em packages/shared — veja CONTRIBUTING.md para as regras de escopo.

Documentação

SETUP.md — guia de self-host e desenvolvimento local
CHANGELOG.md — notas de versão (mais recente: v0.2.0, 2026-05-25 — armazenamento KV)
ROADMAP.md — o que vem a seguir
CONTRIBUTING.md — fluxo de trabalho para contribuidores e escopo OSS
SUBDOMAIN_IMPLEMENTATION.md — roteamento de subdomínios de tenant
docs/runbooks/local-e2e.md — stack E2E multi-região
docs/runbooks — runbooks operacionais
Examples/ — pequenos exemplos de aplicações (todo, lista de compras)
templates/ — aplicações completas que você pode clonar e executar (butterSupport, butterbaseCRM)
Site de documentação (local): http://localhost:4321 após docker compose up

Status do projeto

Versão mais recente: v0.2.0 (2026-05-25) — adiciona o armazenamento KV em SDK / REST / CLI / MCP. O plano de dados é testado em produção pela oferta gerenciada; a distribuição OSS é jovem — por favor, registre problemas de self-host e vamos ajustar a documentação e os padrões com base no feedback. Veja CHANGELOG.md para o histórico completo.

Comunidade e suporte

Discord — converse com a equipe e outros desenvolvedores
LinkedIn — siga-nos para atualizações de produto e anúncios
GitHub Issues — relatórios de bugs, solicitações de recursos
E-mail — yuki@butterbase.ai para contato direto

Contribuindo

Veja CONTRIBUTING.md. A fronteira entre OSS e a oferta gerenciada é intencional — leia a seção de escopo antes de abrir um PR que toque em cobrança, matemática de cotas ou adaptadores de roteador upstream.

Segurança

Veja SECURITY.md. Reporte vulnerabilidades para security@butterbase.ai.

Licença

Contribuidores

Butterbase

Documentação

Recursos

Open-source vs. gerenciado

Início rápido (self-host)

1. Clone (com submódulos)

2. Instale as dependências e configure o env

3. Inicie a stack

4. Execute as migrações do banco de dados

5. Semeie o usuário dev local

6. Teste de fumaça

Endpoints locais

Arquitetura

Estrutura do repositório

O que não está neste repositório

Documentação

Status do projeto

Comunidade e suporte

Contribuindo

Segurança

Licença

Contribuidores

Histórico de estrelas