Installation — bRRAIn Docs

Install bRRAIn using our cloud platform, Docker, or from source. Includes system requirements and configuration.

Installation

bRRAIn can be deployed in three ways: as a fully managed cloud service, as a self-hosted Docker deployment, or built from source for custom environments. This guide covers each option.

The fastest way to start is with the managed bRRAIn Cloud service. No infrastructure setup is required.

  1. Visit app.brrain.io and create an account
  2. Choose your plan (Free tier includes 1 vault and 10,000 memory objects)
  3. Generate an API key from Settings > API Keys
  4. Start making API calls immediately

Cloud deployments are hosted on SOC 2 Type II certified infrastructure with data residency options in the US, EU, and APAC regions.

Option 2: Docker (Self-Hosted)

For organizations that require data to remain on-premises or within their own cloud accounts, bRRAIn provides official Docker images.

System Requirements

| Component | Minimum | Recommended | |-----------|---------|-------------| | CPU | 4 cores | 8+ cores | | RAM | 8 GB | 16+ GB | | Disk | 50 GB SSD | 200+ GB NVMe SSD | | OS | Linux (amd64/arm64) | Ubuntu 22.04 LTS | | Docker | 24.0+ | Latest stable | | Docker Compose | 2.20+ | Latest stable |

Quick Docker Setup

Create a docker-compose.yml file:

version: "3.9"
services:
  brrain:
    image: ghcr.io/qosil/brrain:latest
    ports:
      - "8080:8080"
    environment:
      BRRAIN_DB_URL: "postgres://brrain:secret@db:5432/brrain?sslmode=disable"
      BRRAIN_REDIS_URL: "redis://redis:6379/0"
      BRRAIN_ENCRYPTION_KEY: "${BRRAIN_ENCRYPTION_KEY}"
      BRRAIN_LICENSE_KEY: "${BRRAIN_LICENSE_KEY}"
    depends_on:
      - db
      - redis
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: brrain
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: brrain
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    restart: unless-stopped

volumes:
  pgdata:

Start the services:

# Generate an encryption key
export BRRAIN_ENCRYPTION_KEY=$(openssl rand -base64 32)

# Set your license key (obtain from app.brrain.io/settings/license)
export BRRAIN_LICENSE_KEY="your-license-key"

# Start all services
docker compose up -d

# Verify the deployment
curl http://localhost:8080/healthz

The health endpoint should return {"status":"ok"} once the system is ready.

Running Migrations

After the first startup, run database migrations:

docker compose exec brrain /brrain migrate up

Option 3: Build from Source

For development or custom builds:

# Clone the repository
git clone https://github.com/Qosil/brrain.git
cd brrain

# Install dependencies
go mod download

# Build the binary
go build -o bin/brrain ./cmd/brrain

# Run with required environment variables
export BRRAIN_DB_URL="postgres://localhost:5432/brrain?sslmode=disable"
export BRRAIN_REDIS_URL="redis://localhost:6379/0"
export BRRAIN_ENCRYPTION_KEY=$(openssl rand -base64 32)

./bin/brrain serve

Build Requirements

  • Go 1.25 or later
  • PostgreSQL 15+ (for the metadata store)
  • Redis 7+ (for caching and pub/sub)
  • Node.js 20+ (only if modifying the admin UI)

Configuration

bRRAIn is configured via environment variables. The most important settings are:

| Variable | Description | Default | |----------|-------------|---------| | BRRAIN_PORT | HTTP listen port | 8080 | | BRRAIN_DB_URL | PostgreSQL connection string | Required | | BRRAIN_REDIS_URL | Redis connection string | Required | | BRRAIN_ENCRYPTION_KEY | Base64-encoded 256-bit key for vault encryption | Required | | BRRAIN_LICENSE_KEY | License key for self-hosted deployments | Required | | BRRAIN_LOG_LEVEL | Logging level (debug, info, warn, error) | info | | BRRAIN_CORS_ORIGINS | Comma-separated allowed origins | * | | BRRAIN_MAX_MEMORY_SIZE | Maximum size per memory object in bytes | 1048576 |

For a complete configuration reference, see the Self-Hosting Guide.

Verifying Your Installation

After installation, verify that all components are operational:

# Health check
curl http://localhost:8080/healthz

# Readiness check (verifies database and Redis connectivity)
curl http://localhost:8080/readyz

# Store a test memory
curl -X POST http://localhost:8080/v1/memory/store \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Installation verification test"}'

Next Steps