Installation

Prerequisites

Docker and Docker Compose (recommended)
Python 3.12+ and uv (for running the backend from source)
An OpenAI, Cohere, Voyage, or OpenAI-compatible API key for embeddings
A Turbopuffer API key for managed vector, keyword, and hybrid search

Install

The fastest way to get started. One command starts the full stack:

docker compose up -d

This starts:

bigRAG API on port 4000 (Swagger docs at /docs)
Admin UI on port 3000
PostgreSQL for metadata on port 5432
Redis for the ingestion queue on port 6379

Turbopuffer is configured from the admin UI after setup and provides the managed search backend; it is not a local Compose service.

Pre-built images are published to Docker Hub:

docker pull yoginth/bigrag-api:latest
docker pull yoginth/bigrag-ui:latest

Release artifacts use CalVer (YYYY.M.D). Docker publishes latest for convenience, but production deployments should pin the dated tag from the release they deploy.

Start infrastructure services

docker compose up postgres redis -d

Install and run the backend

cd api
uv sync
uv run python -m bigrag.main

Or with pip:

cd api
python -m venv .venv && source .venv/bin/activate
pip install -e .
python -m bigrag.main

Development Mode

The easiest way to start everything for development:

./dev.sh

This script:

Kills stale processes on port 4000 and old local bigrag-worker processes.
Validates required commands (docker, curl, uv).
Starts Docker services (Postgres and Redis) and waits for readiness.
Installs Python dependencies with uv.
Starts the backend with auto-reload and a bounded /health startup probe.
Starts bigrag-worker with five Dramatiq processes on Redis.
Gracefully stops everything on Ctrl+C.

If the admin UI shows bigrag-worker is offline, check the terminal for the colored work log stream. Each worker-side log line includes the active Dramatiq process label and PID, such as worker=worker-1 pid=12345. Override the local process count with BIGRAG_WORKER_PROCESSES and thread count with BIGRAG_WORKER_THREADS. A healthy local worker should keep running and /v1/stats should report a recent worker heartbeat for the signed-in admin session.

Verify

curl http://localhost:4000/health
# → {"status": "ok", "version": "2026.x.y"}

Interactive Swagger docs are available at http://localhost:4000/docs once the server is running. Database migrations run automatically on startup.