Butterbase

Plataforma de backend full-stack MCP — aprovisiona aplicaciones, gestiona bases de datos, despliega funciones y más.

Documentación

Backend-como-servicio de código abierto, nativo para IA.
Postgres · Auth · Storage · Functions · AI Gateway · Servidor MCP

Sitio web · Discord · LinkedIn · Autoalojamiento · Documentación · Hoja de ruta · Ejemplos · Contribuciones

Butterbase te brinda los componentes básicos para aplicaciones impulsadas por IA sin bloqueos: un backend basado en Postgres con seguridad a nivel de fila, funciones serverless, una puerta de enlace para LLM, suscripciones en tiempo real, almacén clave-valor, almacenamiento de archivos, RAG, actores duraderos por clave y un servidor de Protocolo de Contexto de Modelo (MCP) integrado para que los agentes operen tu backend con herramientas en lugar de código de conexión.

Características

Datos

Plano de datos Postgres — bases de datos por aplicación con esquema declarativo (/schema), endpoints REST automáticos (/auto-api) y migraciones.
Seguridad a nivel de fila — gestión de políticas RLS de primera clase con ayudantes de aislamiento de usuarios (/rls).
Almacén clave-valor — KV regional con protección de cuotas, TTL, registro de auditoría y reglas de exposición en el panel (/v1/:app/kv/*). Nuevo en v0.2.0.
Almacenamiento de archivos — almacenamiento de objetos respaldado por S3/R2 con URL prefirmadas, ACL e indexación asíncrona (/storage).

Cómputo

Funciones serverless — funciones TypeScript ejecutadas en el runtime de Deno (/functions).
Objetos duraderos — actores con estado por clave para salas de chat, multijugador, limitadores de velocidad, agentes de larga duración (/durable-objects).
Tiempo real — suscripciones WebSocket a cambios de tablas para UIs en vivo y presencia (/realtime).
SSR en el borde — despliega manejadores de borde de Next.js / Remix / Astro desde el código fuente (/edge-ssr, /edge-ssr-from-source).
Alojamiento de frontend — despliegues estáticos / SPA desde zip o compilación desde el código fuente con dominios personalizados (/frontend, /custom-domains).

Puerta de enlace de IA — un único endpoint para chat, embeddings, listado de modelos; adaptadores de enrutador conectables (/gateway, /ai-config).
RAG — colecciones gestionadas, ingesta de documentos, búsqueda semántica y respuestas sintetizadas (/rag).
Integraciones — acceso a herramientas de terceros mediante Composio (/integrations).

Identidad y operaciones

Autenticación — correo electrónico + OAuth (Google, GitHub, Apple, X, …), ajuste de JWT, hooks posteriores al inicio de sesión, claves de servicio (/auth, /oauth-config, /api-keys).
Registros de auditoría — registro de auditoría estructurado de solicitudes en KV y otras superficies (/audit-logs).
Webhooks — webhooks salientes para eventos de la aplicación (/webhooks).
Movimientos de aplicaciones multirregión — reubica una aplicación entre regiones conservando réplicas de origen (scripts/move-app/).

Superficie de agentes

Servidor MCP — cada capacidad anterior se expone como herramientas MCP en /mcp (HTTP) o mediante stdio (@butterbase/mcp — npx @butterbase/mcp).
Plugin de Claude Code — packages/plugin (submódulo de butterbase-skills) incluye más de 30 habilidades guiadas (idea → plan → esquema → autenticación → funciones → despliegue → envío) para la creación de aplicaciones con agentes.

Código abierto vs. gestionado

Este repositorio incluye el plano de datos del runtime — todo lo necesario para autoalojar una instancia de Butterbase con todas las funciones. La oferta gestionada en butterbase.ai añade orquestación multirregión, facturación, adaptadores de enrutador de IA ascendentes, aplicación de cuotas basada en arrendamiento y paneles de operaciones (esos viven en un repositorio privado que consume este como submódulo).

Cuando autoalojas, la puerta de enlace de IA se ejecuta sin adaptadores de enrutador ascendentes, la facturación usa un proveedor sin operación y las cuotas son ilimitadas. Conecta tus propias implementaciones mediante las interfaces BillingProvider, QuotaEnforcer y RouterAdapter en packages/shared.

Inicio rápido (autoalojamiento)

Requisitos: Docker, Node 22+, npm.

1. Clonar (con submódulos)

El plugin de Claude Code que contiene las habilidades (packages/plugin) es un submódulo de git (butterbase-skills). Un clon simple deja packages/plugin/ vacío y npm install omite silenciosamente ese espacio de trabajo.

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

Si ya clonaste sin submódulos:

git submodule update --init --recursive

Opcional — mantén los submódulos actualizados en cada pull:

git config --global submodule.recurse true

2. Instalar dependencias y configurar el entorno

npm ci
cp .env.example .env

docker-compose.local.yml configura KV_REDIS_URL_US_EAST_1 por ti. Edita .env solo si anulas los valores predeterminados (por ejemplo, ejecuta control-api en el host — usa redis://localhost:6379).

3. Iniciar la pila

La primera ejecución compila las imágenes y puede tardar varios minutos.

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

Espera hasta que control-api esté saludable:

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

4. Ejecutar migraciones de base de datos

El esquema no se aplica automáticamente al iniciar el contenedor. Desde la raíz del repositorio (con la pila en ejecución):

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. Sembrar el usuario de desarrollo local

Con AUTH_ENABLED=false, la API usa DEV_OWNER_ID de compose. Ese usuario debe existir en platform_users (los volúmenes nuevos comienzan vacíos):

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

6. Prueba de humo

La autenticación está deshabilitada en el perfil de compose local (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 locales

Servicio	URL / puerto
Control API	http://localhost:4000
MCP (HTTP, vía control-api)	http://localhost:4000/mcp
Runtime de Deno	http://localhost:7133
Sitio de documentación	http://localhost:4321
Postgres del plano de control	`localhost:5433`
Postgres del plano de datos	`localhost:5435`
Postgres del plano de runtime	`localhost:5437`
LocalStack (S3)	http://localhost:4566

Configuración completa (autenticación, clientes MCP, solución de problemas, notas de producción): SETUP.md.

Arquitectura

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

Tres planos Postgres:

plano de control (db/control-plane/) — metadatos de la plataforma: usuarios, aplicaciones, facturación, auditoría.
plano de runtime (db/runtime-plane/) — tablas de runtime de ruta crítica (reglas de exposición KV, canales en tiempo real, sesiones).
plano de datos (db/data-plane/) — datos de usuario por aplicación; cada aplicación obtiene esquemas aislados con RLS.

Estructura del repositorio

Servicios (services/)

Servicio	Lenguaje	Qué hace
`control-api`	Node.js / Fastify	Punto de entrada principal. Todas las API públicas, incluye MCP en `/mcp`.
`mcp-server`	Node.js	Implementaciones de herramientas MCP (integradas en control-api; también se distribuye como binario stdio `butterbase-mcp`).
`deno-runtime`	Deno	Ejecuta funciones serverless de usuario en aislamientos.
`agent-runtime`	Python (uv)	Ejecutor de agentes de larga duración para tareas de `manage_ai` / agentes.
`build-runner`	Cloudflare Worker	Compila frontends y paquetes edge-SSR desde el código fuente.
`storage-indexer`	Node.js	Indexador asíncrono para objetos subidos.
`docs`	Astro	Sitio de documentación pública (también servido localmente en `:4321`).

Paquetes (packages/)

Paquete	Descripción
`@butterbase/sdk`	SDK universal de TypeScript (navegador + servidor).
`@butterbase/cli`	CLI de `butterbase` para scaffolding y gestión de backend.
`@butterbase/plugin`	Plugin de Claude Code — más de 30 habilidades guiadas para la creación de aplicaciones con IA. Submódulo de git de butterbase-skills.
`@butterbase/shared`	Tipos compartidos, constantes e interfaces conectables (`BillingProvider`, `QuotaEnforcer`, `RouterAdapter`).

Otras piezas de nivel superior

dispatch-worker/ — Cloudflare Worker que enruta el tráfico de subdominios por aplicación.
bb-placeholder/ — origen de marcador de posición para subdominios no aprovisionados.
infra/ — configuraciones de pgbouncer y traefik para autoalojamiento.
db/ — migraciones SQL para los tres planos Postgres.
Examples/ — todo-2026-04-02, grocery-list-2026-04-03.
templates/ — aplicaciones completas con forma de producción: butterSupport, butterbaseCRM.

Lo que no está en este repositorio

El límite entre OSS / gestionado es intencional. Lo siguiente es privado de la oferta gestionada:

Orquestación multirregión y el programador entre regiones.
Lógica de facturación, matemática de cuotas basada en arrendamiento y conexión con Stripe más allá del proveedor sin operación.
Adaptadores de enrutador de IA ascendentes (integraciones de proveedores OpenAI / Anthropic / Bedrock más allá de la interfaz de la puerta de enlace).
Paneles de clientes / administradores, paneles de anfitriones de hackathons y herramientas de operaciones.

Si necesitas estos para autoalojar, implementa contra las interfaces en packages/shared — consulta CONTRIBUTING.md para las reglas de alcance.

Documentación

SETUP.md — guía de autoalojamiento y desarrollo local
CHANGELOG.md — notas de versión (última: v0.2.0, 2026-05-25 — almacén KV)
ROADMAP.md — qué sigue
CONTRIBUTING.md — flujo de trabajo para contribuyentes y alcance OSS
SUBDOMAIN_IMPLEMENTATION.md — enrutamiento de subdominios de inquilinos
docs/runbooks/local-e2e.md — pila E2E multirregión
docs/runbooks — manuales operativos
Examples/ — aplicaciones de ejemplo pequeñas (todo, lista de compras)
templates/ — aplicaciones completas que puedes clonar y ejecutar (butterSupport, butterbaseCRM)
Sitio de documentación (local): http://localhost:4321 después de docker compose up

Estado del proyecto

Última versión: v0.2.0 (2026-05-25) — añade el almacén KV en SDK / REST / CLI / MCP. El plano de datos está probado en producción por la oferta gestionada; la distribución OSS es joven — por favor, reporta problemas de autoalojamiento y ajustaremos la documentación y los valores predeterminados según los comentarios. Consulta CHANGELOG.md para el historial completo.

Comunidad y soporte

Discord — conversa con el equipo y otros desarrolladores
LinkedIn — síguenos para actualizaciones de producto y anuncios
GitHub Issues — informes de errores, solicitudes de funciones
Correo electrónico — yuki@butterbase.ai para contacto directo

Contribuciones

Consulta CONTRIBUTING.md. El límite entre OSS y la oferta gestionada es intencional — por favor, lee la sección de alcance antes de abrir un PR que toque facturación, matemática de cuotas o adaptadores de enrutador ascendentes.

Seguridad

Consulta SECURITY.md. Reporta vulnerabilidades a security@butterbase.ai.

Licencia

Contribuyentes

Butterbase

Documentación

Características

Código abierto vs. gestionado

Inicio rápido (autoalojamiento)

1. Clonar (con submódulos)

2. Instalar dependencias y configurar el entorno

3. Iniciar la pila

4. Ejecutar migraciones de base de datos

5. Sembrar el usuario de desarrollo local

6. Prueba de humo

Endpoints locales

Arquitectura

Estructura del repositorio

Lo que no está en este repositorio

Documentación

Estado del proyecto

Comunidad y soporte

Contribuciones

Seguridad

Licencia

Contribuyentes

Historial de estrellas