Skip to main content

​
Choose your installation method

Brainbox offers multiple deployment options to fit your workflow and infrastructure requirements.

Web app

Fastest setup—no installation required

Desktop app

Native app with offline-first support

Self-hosted

Full control on your infrastructure

​
Web app installation

The web app runs entirely in your browser with no server installation required.

​
Requirements

Browser compatibility: Chrome 102+, Edge 102+, or Firefox 111+ required. Safari and mobile browsers are not currently supported due to OPFS (Origin Private File System) requirements.
  • Modern browser with OPFS support
  • Stable internet connection for initial setup
  • ~50MB storage for local database

​
Getting started

1

Visit the app

Navigate to brainbox.sh in a supported browser
2

Create an account

Sign up with email or Google OAuth
// Uses @brainbox/client mutations
await executeMutation({
  type: 'email.register',
  email: 'user@example.com',
  password: 'secure-password',
  name: 'Your Name'
});
3

Browser grants storage access

The app will request OPFS access to create a local SQLite database
4

Start using Brainbox

Create workspaces and pages—all data syncs automatically

​
How it works

The web app uses WebAssembly SQLite running in a Web Worker: 
// From apps/web/src/main.tsx
import * as Comlink from 'comlink';
import { ColanodeWorkerApi } from '@brainbox/web/lib/types';
import DedicatedWorker from '@brainbox/web/workers/dedicated?worker';

const worker = new DedicatedWorker();
const workerApi = Comlink.wrap<ColanodeWorkerApi>(worker);

window.brainbox = {
  init: async () => {
    await workerApi.init();
  },
  executeMutation: async (input) => {
    return workerApi.executeMutation(input);
  },
  executeQuery: async (input) => {
    return workerApi.executeQuery(input);
  }
};
All changes save to your local browser database first, then sync to the server in the background.

​
Desktop app installation

The desktop app provides native performance with better-sqlite3 and full offline support.

​
System requirements

  • macOS: 10.13 (High Sierra) or later
  • Windows: Windows 10 or later
  • Linux: Ubuntu 18.04+, Fedora 32+, or Debian 10+
  • ~200MB disk space
  • Node.js not required for end users

​
Download and install

1

Download

Get the latest .dmg file from GitHub Releases
2

Install

  1. Open the .dmg file
  2. Drag Brainbox to your Applications folder
  3. Right-click and select Open (first launch only)
3

Launch

Open Brainbox from Applications and sign in or create an account

​
Desktop app features

Native SQLite

Uses better-sqlite3 for maximum performance

True offline mode

Work without any internet connection

File system access

Direct access to local files and folders

Auto-updates

Automatic updates via update-electron-app

​
Self-hosted installation

Deploy Brainbox on your own infrastructure for complete control and data sovereignty.

​
Prerequisites

# Docker 20.10+ and Docker Compose 2.0+
docker --version
docker compose version

​
Quick start with Docker

1

Clone the repository

git clone https://github.com/brainbox/brainbox.git
cd brainbox/hosting/docker
2

Configure environment

cp .env.example .env
Edit .env with your settings:
.env
# Set secure passwords
POSTGRES_PASSWORD=your-secure-postgres-password
VALKEY_PASSWORD=your-secure-redis-password  
MINIO_ROOT_PASSWORD=your-secure-minio-password

# Account settings
ACCOUNT_VERIFICATION_TYPE=automatic  # or 'email' or 'manual'

# Optional: Storage limits
USER_STORAGE_LIMIT=10737418240      # 10 GB per user
USER_MAX_FILE_SIZE=104857600        # 100 MB max file
3

Start services

docker compose up -d
This starts:
  • PostgreSQL 17 with pgvector extension
  • Valkey 8.1 (Redis fork) for caching
  • MinIO for S3-compatible object storage
  • Brainbox server (Fastify API on port 3000)
  • Brainbox web (React app on port 4000)
4

Access your instance

Open http://localhost:4000 and create your first account
MinIO console is available at http://localhost:9001 using the credentials from .env

​
Infrastructure requirements

For small teams (5-10 users):
  • CPU: 2 cores
  • RAM: 4GB
  • Storage: 20GB SSD
  • Network: 100 Mbps

​
Environment configuration

Key environment variables from apps/server/.env.example: 
# PostgreSQL connection
POSTGRES_URL=postgres://user:pass@localhost:5432/brainbox

# Optional SSL settings
# POSTGRES_SSL_REJECT_UNAUTHORIZED=false
# POSTGRES_SSL_CA=/path/to/ca.crt

​
Kubernetes deployment

For production-grade deployments: 
helm repo add brainbox https://charts.brainbox.dev
helm install brainbox brainbox/brainbox \
  --set postgresql.auth.password=your-password \
  --set redis.auth.password=your-redis-password \
  --set minio.rootPassword=your-minio-password

Kubernetes guide

See the full Kubernetes installation guide for advanced configurations

​
Verify installation

Check that all services are running: 
# View container status
docker compose ps

# Check logs
docker compose logs server
docker compose logs web

# Test database connection  
docker exec -it brainbox_postgres psql -U colanode_user -d colanode_db
Expected output: 
NAME                 STATUS   PORTS
brainbox_postgres    Up       5432
brainbox_valkey      Up       6379  
brainbox_minio       Up       9000-9001
brainbox_server      Up       3000
brainbox_web         Up       4000->80

​
Development installation

For contributors and developers building custom features:
1

Clone and install

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

Start infrastructure

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

Configure server

cd apps/server
cp .env.example .env
# Edit .env with local development values
4

Start development servers

# From repository root
npm run dev
This starts:
  • API server: http://localhost:3000
  • Web app: http://localhost:4000
  • Desktop app: Electron window

Development guide

See the full development setup guide for detailed instructions

​
Next steps

Quickstart guide

Create your first workspace and pages

Configuration

Advanced server and deployment configuration

Troubleshooting

Common issues and solutions

Architecture

Learn how Brainbox works under the hood
Need help? Report installation issues on GitHub Issues or ask in Discussions.

Build docs developers (and LLMs) love

Get started for freeTalk to us