Configuration

bigRAG uses a UI-first configuration model. Operators provide only the wiring needed before the API can read Postgres, then admins manage product/runtime settings from /settings and /models.

Auth is admin accounts + session cookies and minted bigrag_sk_… API keys — see Authentication.

Bootstrap config

Bootstrap config is the small set of values the API needs before it can connect to the database and decrypt saved settings.

Two variables to note:

• BIGRAG_DATABASE_URL preserves Postgres sslmode settings. Use sslmode=require, verify-ca, or verify-full for hosted Postgres TLS; use sslmode=disable only for local or trusted private networks.
• BIGRAG_MASTER_KEY_PREVIOUS is dual-read during rotation for encrypted secrets and API-key hash lookup. Keep old keys there until encrypted rows and minted API keys have been rewritten or replaced.

The admin UI has one frontend bootstrap value: point it at the API with VITE_BIGRAG_URL at build/dev time or BIGRAG_URL in the app container when frontend and backend are deployed separately.

Worker

Run background jobs with bigrag-worker. The worker reads the same BIGRAG_ environment and accepts these flags:

The worker parent runs database migrations once before spawning Dramatiq processes; child processes skip migration bootstrap. The local dev script and Docker Compose default to BIGRAG_WORKER_PROCESSES=5 and BIGRAG_WORKER_THREADS=8.

TOML bootstrap file

The CLI can also read a bigrag.toml file. Keep this file to bootstrap wiring:

env = "prod"
log_level = "info"
log_format = "json"
host = "0.0.0.0"
port = 4000
workers = 1

database_url = "postgres://bigrag:change-me@postgres:5432/bigrag?sslmode=disable"
redis_url = "redis://redis:6379/0"

master_key = "generate-a-fernet-key"
master_key_previous = []

upload_dir = "./data/uploads"
conversion_device = "cpu"

Environment variables override TOML values. CLI flags passed to python -m bigrag.main override both.

Runtime settings

After the first admin account exists, the admin UI sends first-run operators to /onboarding to create one verified embedding preset and save Turbopuffer settings. The Turbopuffer step's Save and Finish action saves the vector settings and opens /overview.

Later, manage settings at:

Turbopuffer is the search backend for every collection. Settings are stored in Postgres in the instance_settings table; secret settings are encrypted with BIGRAG_MASTER_KEY and redacted on read.

BIGRAG_CHAT_API_KEY can seed a default instance chat credential for OpenAI's standard API endpoint. For non-default chat_base_url values, configure a saved chat key in the admin UI or pass provider_api_key on chat requests so the instance fallback key is never sent to a custom provider.

The same settings are available through /v1/admin/settings. Database-backed admin settings apply immediately on save. Turbopuffer connection changes validate the new target before saving, then swap the runtime client in place where applicable.

CLI flags

python -m bigrag.main accepts bootstrap overrides:

--config PATH            Path to bigrag.toml
--host HOST              Override server host
--port PORT              Override server port
--database-url URL       Override Postgres URL
--redis-url URL          Override Redis URL