"앱 하나 만들 때 필요한 백엔드 부품(DB·로그인·파일저장·함수실행·AI호출)을 통째로 셀프호스팅으로 띄우고, 그 전부를 AI 에이전트가 자동으로 운전하게 해주는 오픈소스 플랫폼"입니다. Firebase나 Supabase처럼 "백엔드를 빌려 쓰는" 서비스인데, 코드를 한 줄도 안 쓰고 AI가 스키마를 짜고 인증을 켜고 함수를 배포하도록 설계됐다는 점이 다릅니다.
이름의 유래도 직관적입니다. Supabase·Firebase처럼 "base(기반)"를 공유하되, 버터처럼 매끄럽게(butter-smooth) 발라진다는 농담 섞인 작명입니다. 라이선스는 Apache-2.0, 저작권자는 NetGPT Inc.이며 2026년에 새로 등장해 TrendShift 일간 1위에 올랐습니다.
보통 식당(앱)을 열려면 냉장고(DB)·금고(인증)·창고(스토리지)·가스레인지(함수 실행)를 따로따로 사서 배선해야 합니다. butterbase는 이 부품들을 한 박스에 담아 셀프호스팅으로 배달합니다.
여기에 결정적 한 가지가 더 있습니다. 주방의 모든 장비에 표준 리모컨 단자(MCP)가 달려 있어서, AI 요리사(에이전트)가 "스키마 만들어줘 → 로그인 켜줘 → 함수 배포해줘"를 사람 손 없이 직접 누를 수 있습니다.
/mcp 엔드포인트의 MCP 도구로 노출해, 에이전트가 API 글루 코드 없이 백엔드를 직접 조작하게 한다.2026년 들어 "AI 에이전트가 앱을 통째로 만든다"는 흐름(이른바 바이브 코딩)이 폭발했습니다. 그런데 막상 에이전트가 코드를 짜도, 백엔드를 띄우고 연결하는 부분은 여전히 사람이 손으로 해야 했습니다. butterbase는 바로 이 마지막 빈칸을 노립니다. "에이전트가 백엔드까지 직접 운영한다"는 포지셔닝이 시기와 정확히 맞물려 일간 1위에 올랐습니다.
| 항목 | Firebase | Supabase | butterbase |
|---|---|---|---|
| 오픈소스 | ✕ (폐쇄) | ○ | ○ (Apache-2.0) |
| DB | NoSQL(Firestore) | Postgres | Postgres (3-plane 분리) |
| 셀프호스팅 | 불가 | 가능(복잡) | Docker compose 한 방 |
| AI 게이트웨이 | 일부(Genkit) | 외부 연동 | 내장 (채팅·임베딩·RAG) |
| 에이전트 제어(MCP) | ✕ | 제한적 | 모든 기능이 MCP 도구 |
| 함수 런타임 | Node | Deno(Edge Functions) | Deno + Python 에이전트 런타임 |
보통 에이전트가 백엔드를 다루려면 "이 API를 이렇게 호출해" 식의 연결 코드(글루 코드)를 매번 짜야 합니다. butterbase는 DB 스키마 선언, RLS 정책, 함수 배포, KV 저장, RAG 검색까지 전부 MCP 도구로 노출합니다. 에이전트는 "도구를 호출"하기만 하면 됩니다.
이 저장소는 런타임 데이터 플레인 전체를 담아, 셀프호스팅만으로 완전한 기능을 쓸 수 있습니다. 멀티리전 오케스트레이션·과금·상용 AI 라우터 같은 매니지드 전용 기능은 분리돼 있고, 필요하면 packages/shared의 인터페이스(BillingProvider·QuotaEnforcer·RouterAdapter)에 직접 구현을 끼워 넣으면 됩니다.
Postgres·RLS·KV·파일스토리지·서버리스 함수·Durable Objects·실시간 구독·Edge SSR·프론트엔드 호스팅·인증·AI 게이트웨이·RAG가 한 박스에 있습니다. 여러 SaaS를 조립할 필요 없이 docker compose up 한 번으로 전부 뜹니다.
Supabase가 "Firebase의 오픈소스 대안"이었다면, butterbase는 "Supabase의 AI 에이전트 시대 버전"이다. 차이는 사람이 대시보드를 클릭하느냐, AI가 MCP 도구를 호출하느냐다.
butterbase는 단일 언어 프로젝트가 아니라, 역할별로 최적의 언어/런타임을 고른 폴리글랏(polyglot) 모노레포입니다. npm 워크스페이스(packages/*, services/*)로 묶여 있습니다.
| 서비스 | 언어/런타임 | 역할 |
|---|---|---|
| control-api | Node.js / Fastify | 메인 진입점. 모든 공개 API를 처리하고 /mcp에 MCP 서버를 내장 |
| mcp-server | Node.js | MCP 도구 구현. control-api에 빌트인 + butterbase-mcp stdio 바이너리로도 배포 |
| deno-runtime | Deno | 사용자 서버리스 함수를 격리(isolate) 환경에서 실행 |
| agent-runtime | Python (uv) | 장시간 도는 에이전트 실행기 (manage_ai·에이전트 작업) |
| build-runner | Cloudflare Worker | 소스에서 프론트엔드·Edge-SSR 번들을 빌드 |
| storage-indexer | Node.js | 업로드된 객체를 비동기로 인덱싱 |
| docs | Astro | 공개 문서 사이트 (로컬 :4321) |
| 패키지 | 설명 |
|---|---|
| @butterbase/sdk | 브라우저+서버 양쪽에서 쓰는 범용 TypeScript SDK |
| @butterbase/cli | butterbase 명령어 — 스캐폴딩·백엔드 관리 CLI |
| @butterbase/plugin | Claude Code 플러그인 — 40개 이상의 가이드형 스킬 (아이디어→스키마→인증→함수→배포). butterbase-skills 저장소의 git 서브모듈 |
| @butterbase/shared | 공유 타입·상수 + 갈아끼우는 인터페이스(BillingProvider·QuotaEnforcer·RouterAdapter) |
| 구성요소 | 역할 |
|---|---|
| Postgres ×3 | control / runtime / data 3개 플레인으로 물리 분리 (뒤 섹션 참고) |
| Redis | KV 스토어 백엔드 (리전별, TTL·쿼터·감사 로그) |
| S3 / R2 + LocalStack | 파일 스토리지. 로컬은 LocalStack(:4566)으로 S3 흉내 |
| Cloudflare Workers | build-runner·dispatch-worker (앱별 서브도메인 라우팅) |
| pgbouncer / traefik | 커넥션 풀링 / 리버스 프록시 (infra/) |
| Docker Compose | 셀프호스팅 전체 스택을 한 파일로 기동 (docker-compose.local.yml) |
butterbase 아키텍처에서 가장 배울 점은 두 가지입니다. ① control-api라는 단일 진입점이 모든 요청을 받고 뒤의 전문 일꾼들에게 분배하는 구조, 그리고 ② Postgres를 역할별로 3개로 쪼갠 멀티 플레인 설계입니다.
모든 클라이언트(내 앱·에이전트·CLI)는 오직 control-api 한 곳으로만 말을 겁니다. control-api가 인증을 확인하고, 요청을 적절한 백엔드(Postgres·Redis·Deno·Python)로 라우팅합니다. MCP 서버도 별도 프로세스가 아니라 control-api의 /mcp 경로에 내장돼 있습니다.
호텔 프런트 데스크와 같다. 손님(클라이언트)은 객실 청소부·주방·발렛에게 직접 전화하지 않는다. 프런트(control-api) 한 곳에 요청하면, 프런트가 신원을 확인하고 알맞은 부서로 연결한다. AI 에이전트용 "리모컨 단자(MCP)"도 같은 프런트에 붙어 있다.
하나의 거대한 DB를 쓰지 않고, 역할이 다른 데이터를 물리적으로 다른 Postgres로 분리했습니다. 이게 멀티테넌트(여러 고객 앱을 한 플랫폼에 수용) 설계의 정석입니다.
| 플레인 | 위치 | 담는 데이터 |
|---|---|---|
| control-plane | db/control-plane/ | 플랫폼 메타데이터: 사용자·앱·과금·감사 로그 |
| runtime-plane | db/runtime-plane/ | 핫패스 런타임 테이블: KV 노출 규칙·실시간 채널·세션 |
| data-plane | db/data-plane/ | 앱별 사용자 데이터. 각 앱이 RLS로 격리된 스키마를 받음 |
플랫폼 운영 데이터(누가 가입했나)와 고객 앱의 실제 데이터를 섞으면, 한쪽 장애가 전체를 무너뜨린다. 분리하면 data-plane만 리전별로 복제·이동할 수 있고(README의 "멀티리전 앱 이동"), 보안 사고의 영향 범위도 좁아진다.
여러 앱·여러 사용자가 같은 data-plane Postgres를 공유하는데, 어떻게 서로의 데이터를 못 보게 막을까요? 답은 RLS입니다. 테이블 한 줄(row) 단위로 "이 사용자는 이 행만 볼 수 있다"는 정책을 DB 자체에 박아 둡니다. 애플리케이션 코드가 깜빡 잊어도 DB가 강제로 막아 줍니다.
/rls API로 이 정책을 일급(first-class)으로 관리하고, 사용자 격리 헬퍼를 제공한다. 멀티테넌트 SaaS의 핵심 안전장치.서버리스 함수는 보통 무상태(stateless)입니다 — 실행이 끝나면 기억이 사라집니다. 그런데 채팅방·멀티플레이어·레이트 리미터처럼 "상태를 계속 들고 있어야" 하는 게 있죠. butterbase의 Durable Objects는 키(key)별로 살아 있는 작은 액터를 만들어, 한 채팅방=하나의 영속 객체처럼 다룹니다.
services/ ↔ packages/ 의 구분이 핵심입니다. services/는 "서버에서 돌아가는 프로세스", packages/는 "남이 설치해 쓰는 라이브러리"입니다. 이 둘을 npm 워크스페이스로 한 저장소에 묶은 게 모노레포 전략이고, db/가 3개로 나뉜 건 앞서 본 멀티 플레인 설계의 흔적입니다.
packages/plugin은 별도 저장소(butterbase-skills)의 서브모듈이다. 그냥 git clone하면 이 폴더가 비고, npm install이 해당 워크스페이스를 조용히 건너뛴다. 반드시 git clone --recurse-submodules 또는 git submodule update --init --recursive를 써야 한다.
butterbase는 "여러 고객 앱을 한 플랫폼이 안전하게 수용하는 법"의 살아있는 교본입니다. 3-plane 분리 + RLS 격리 + 앱별 스키마라는 조합을 코드로 확인하세요. 실습: 작은 Postgres 하나에 RLS 정책을 직접 걸어, 두 사용자가 같은 테이블을 봐도 서로의 행은 못 보게 만들어 보기.
"내 백엔드 기능을 AI 에이전트가 도구로 쓰게 노출"하는 방법을 services/mcp-server에서 배울 수 있습니다. 실습: npx @butterbase/mcp로 stdio MCP 서버를 띄우고, Claude Code/Cursor에 연결해 "앱 하나 만들어줘"를 도구 호출로 처리하는 흐름을 관찰하기.
Node·Deno·Python·Cloudflare Worker가 한 저장소에서 npm 워크스페이스로 공존합니다. package.json의 workspaces, build --workspaces --if-present 패턴을 보세요. 실습: 2개 패키지짜리 미니 워크스페이스를 만들어, 한쪽이 다른 쪽을 의존하도록 구성해 보기.
deno-runtime이 사용자 코드를 isolate에 가둬 실행하는 구조는 "남의 코드를 내 서버에서 안전하게 돌리는" 모든 플랫폼(Vercel·Cloudflare·Supabase)의 공통 주제입니다. 실습: Deno의 권한 플래그(--allow-net 등)를 켜고 꺼보며 샌드박스 경계를 체감하기.
Postgres 3개 + Redis + LocalStack + 여러 서비스가 docker-compose.local.yml 하나로 뜹니다. 헬스체크(/health/ready) 기반 기동 순서, 포트 매핑, 볼륨 설계가 좋은 참고 자료입니다. 실습: compose 파일을 읽고 각 서비스의 의존 관계를 직접 그려 보기.
packages/plugin의 40여 개 스킬은 "아이디어→계획→스키마→인증→함수→배포→제출"을 단계별로 가이드합니다. 실습: 스킬 하나의 SKILL.md를 열어, 에이전트에게 어떤 순서·제약을 주입하는지 분석하기.
| 항목 | 요구사항 |
|---|---|
| Docker | 필수 — 전체 스택을 컨테이너로 기동 |
| Node.js | 빌드 노드 24.14.0 기준 (공식 engines 필드 미선언 — 셀프호스팅 SETUP.md 참조) |
| npm | 워크스페이스 설치(npm ci) |
| 메모리/시간 | 첫 기동은 이미지 빌드로 수 분 소요. Postgres 3개+Redis+LocalStack+서비스 다수가 동시에 떠 RAM 여유 권장 |
| git | 서브모듈 포함 클론 필요(--recurse-submodules) |
| 서비스 | 주소/포트 |
|---|---|
| Control API | http://localhost:4000 |
| MCP (HTTP) | http://localhost:4000/mcp |
| Deno 런타임 | http://localhost:7133 |
| 문서 사이트 | http://localhost:4321 |
| control-plane Postgres | localhost:5433 |
| data-plane Postgres | localhost:5435 |
| runtime-plane Postgres | localhost:5437 |
| LocalStack (S3) | http://localhost:4566 |
컨테이너가 떠도 DB 마이그레이션은 자동 실행되지 않는다. 스택 기동 후 npm run migrate:all을 직접 돌려야 한다. 또 AUTH_ENABLED=false 로컬 프로필에서는 DEV_OWNER_ID 유저가 platform_users에 존재해야 하므로 npm run seed:dev로 시드해야 한다. 새 볼륨은 비어 있다.
README의 Quickstart를 그대로 따라 docker compose up → migrate:all → seed:dev를 완주하고, curl -X POST .../init으로 첫 앱을 생성한 뒤 /apps로 조회한다. 각 단계가 어느 플레인을 건드리는지 메모하기.
npx @butterbase/mcp를 Claude Code나 Cursor에 연결하고, 자연어로 "유저 테이블 만들고 RLS 켜줘"를 시켜 본다. 에이전트가 어떤 MCP 도구를 어떤 순서로 호출하는지 로그로 추적하기.
Deno 함수 하나를 배포해, 요청이 올 때마다 KV 스토어의 카운터를 +1 하고 TTL을 거는 방문자 카운터를 만든다. /functions와 /v1/:app/kv/* API를 함께 써 보기.
/rag API로 컬렉션을 만들고 문서 몇 개를 인제스트한 뒤, 시맨틱 검색 + 합성 답변을 받아 본다. AI 게이트웨이(/gateway)의 임베딩 엔드포인트와 어떻게 맞물리는지 추적하기.
셀프호스팅은 상용 AI 라우터가 빠져 있다. packages/shared의 RouterAdapter 인터페이스를 구현해, OpenAI나 Anthropic 호출을 직접 연결한다. OSS/매니지드 경계를 코드로 체득하는 과제.
| 주차 | 학습 주제 | 실천 목표 |
|---|---|---|
| 1주차 | Postgres + RLS 기초 | 로컬 Postgres에 RLS 정책 직접 작성, 멀티테넌트 격리 실험 |
| 2주차 | BaaS 개념 + Supabase 비교 | Supabase 셀프호스팅과 butterbase를 나란히 띄워 구조 차이 정리 |
| 3주차 | MCP 프로토콜 | 간단한 MCP 서버를 직접 구현(FastMCP/TS SDK), 도구 3개 노출 |
| 4주차 | Deno + 서버리스 함수 | isolate 권한 모델 학습, 샌드박스 함수 배포 파이프라인 구성 |
| 5주차 | Docker Compose 오케스트레이션 | 다중 서비스+헬스체크+볼륨을 갖춘 나만의 compose 작성 |
| 6주차 | RAG + AI 게이트웨이 | 임베딩→벡터검색→합성답변 전 과정을 직접 구축 |
| 7주차 | Durable Objects / 액터 모델 | 상태 있는 채팅방·레이트리미터를 액터로 구현 |
| 8주차 | 플랫폼 엔지니어링 종합 | OSS/매니지드 경계 설계, 인터페이스 기반 확장 포인트 설계 연습 |
packages/plugin이 butterbase-skills를 서브모듈로 가져온다.| 링크 | 설명 |
|---|---|
| GitHub 저장소 | 소스 전체. README.md·SETUP.md·db/·services/가 핵심 |
| butterbase.ai | 공식 웹사이트(매니지드 오퍼링) |
| TrendShift 페이지 | 트렌딩 추이(일간 1위, 2026-06-09) |
| butterbase-skills | Claude Code 플러그인 스킬 모음(서브모듈 원본) |
| Model Context Protocol | MCP 공식 사양·SDK |
| Postgres RLS 문서 | 행 단위 보안 정책의 공식 레퍼런스 |
| Fastify | control-api를 떠받치는 Node 웹 프레임워크 |
| Deno | 서버리스 함수 런타임 |
| Supabase 문서 | 가장 가까운 경쟁/비교 대상. 구조 비교 학습용 |