Brainbox

Local-first collaboration workspace you can self-host

A privacy-focused alternative to Notion that works offline. Own your data, collaborate in real-time, and keep everything in sync across devices.

What's Inside

• Rich text editor - Notion-like pages with blocks, formatting, and embeds
• Databases - Custom fields, multiple views (table, kanban, calendar)
• Real-time chat - Instant messaging for teams
• File storage - Upload and manage files in secure workspaces
• Offline-first - Work without internet, sync when reconnected
• CRDT collaboration - Multiple users editing simultaneously
• Self-hosted - Your data, your server, your control

Quick Start

Try it online: brainbox.3pe1x.com

Early preview - expect some bugs

Self-host with Docker:

git clone https://github.com/brainbox/brainbox.git
cd brainbox
docker compose -f hosting/docker/docker-compose.yaml up -d

Access at http://localhost:3000

How It Works

Local-first sync:

1. Each client has a local SQLite database
2. Changes save locally first (works offline)
3. Background sync to server when connected
4. CRDTs handle conflict resolution via Yjs

Tech stack:

• Frontend: React + TypeScript + TailwindCSS v4
• Backend: Fastify + PostgreSQL + Redis + S3
• Desktop: Electron
• Build: Turbo monorepo

Development

Prerequisites:

• Node.js 18+, npm 10+
• Docker & Docker Compose

Setup:

git clone https://github.com/brainbox/brainbox.git
cd brainbox
npm install

# Start infrastructure (postgres, redis, minio)
docker compose -f hosting/docker/docker-compose.yaml up -d

# Configure environment
cd apps/server
cp .env.example .env

# Start all dev servers
npm run dev

Run individual services:

cd apps/server && npm run dev  # API (port 3000)
cd apps/web && npm run dev     # Web (port 4000)
cd apps/desktop && npm run dev # Desktop

Project structure:

brainbox/
├── apps/
│   ├── server/   # Fastify API
│   ├── web/      # React web app
│   └── desktop/  # Electron app
├── packages/
│   ├── core/     # Shared types & utils
│   ├── crdt/     # Yjs CRDT implementation
│   ├── client/   # Sync engine
│   └── ui/       # Component library
└── hosting/      # Docker & K8s configs

Commands:

npm run dev      # Start dev servers
npm run build    # Build all packages
npm run test     # Run tests (Vitest)
npm run lint     # Lint & format
npm run compile  # Type check

Deployment

Requirements:

• PostgreSQL with pgvector extension
• Redis (or Valkey)
• S3-compatible storage

Docker Compose:

docker compose -f hosting/docker/docker-compose.yaml up -d

Kubernetes:

helm repo add brainbox https://charts.brainbox.dev
helm install brainbox brainbox/brainbox \
  --set postgresql.auth.password=your-password

See hosting/kubernetes/README.md for details.

Key environment variables:

DATABASE_URL=postgresql://user:pass@host:5432/brainbox
REDIS_URL=redis://host:6379
S3_ENDPOINT=https://your-s3.com
S3_ACCESS_KEY=key
S3_SECRET_KEY=secret
JWT_SECRET=your-secret

Troubleshooting

Database connection issues:

docker exec -it brainbox-postgres psql -U brainbox -d brainbox

Build failures:

npm run clean
rm -rf node_modules package-lock.json
npm install

Need help?

• Check docs/ folder
• Report bugs: GitHub Issues

Contributing

Contributions welcome!

Workflow:

1. Fork and clone
2. Create feature branch: git checkout -b feature/name
3. Make changes, write tests
4. Use conventional commits: feat: add thing
5. Submit PR

Before submitting:

npm run lint
npm run test
npm run build

Commit types: feat:, fix:, docs:, refactor:, test:, chore:

Sponsors & Supporters

CodeRabbit

License

Apache 2.0 - see LICENSE