Configuration reference

Every env var Bigwave reads, the Settings field it maps to, and sensible defaults. Unless noted, all are optional.

The installer writes a .env file at the repo root with the values your axis selections imply; uvicorn / systemd / docker-compose all source this file, so the variables below land in the API process without further wiring.

Naming convention. Each axis selector is a bare noun (BIGWAVE_GATEWAY, BIGWAVE_VECTOR, …). Per-backend connection knobs keep their backend prefix (BIGWAVE_QDRANT_URL, BIGWAVE_PHOENIX_ENDPOINT).

Required

BIGWAVE_ADMIN_TOKEN

The bearer token clients send in Authorization: Bearer <token>. The API process refuses to boot without it.

BIGWAVE_ADMIN_TOKEN=$(openssl rand -hex 32)

The installer generates one for you and prints a masked banner at the end of ./install.sh. Pass --show-token to print the full value (the default is <prefix>… (N chars; full value in .env) so the secret doesn't end up in CI logs or terminal scrollback).

Gateway

BIGWAVE_GATEWAY

Which gateway adapter to mount on /v1/*. Default: firstparty.

Value	Behaviour
firstparty	In-tree FastAPI dispatching to a ServingEngine. Owns every bigwave-extension surface — agent loop, RAG injection, fallback chain, per-completion feedback API, /v1/messages Anthropic translation.
litellm	Wraps litellm.acompletion for 100+-provider routing breadth (Anthropic, Bedrock, Vertex, Together, Groq, OpenAI). Drops the bigwave-specific extensions (see ADR 0021). Requires pip install 'bigwave[litellm]'.

The composition root mounts extension routers based on the adapter's declared Gateway.capabilities() set. Selecting litellm silently omits the feedback router etc.; selecting firstparty mounts them.

BIGWAVE_LITELLM_DEFAULT_MODEL

When gateway=litellm. Model id used when a request omits model. LiteLLM's prefix routing applies — ollama/llama3.2:3b, claude-sonnet-4, gpt-4o, etc. Default: empty (falls back to BIGWAVE_MODEL).

BIGWAVE_LITELLM_FALLBACK_MODELS

When gateway=litellm. Comma-separated list passed to litellm's own fallbacks= parameter. Different mechanism from BIGWAVE_FALLBACK_MODELS (which is the firstparty in-process fallback chain).

Core serving

BIGWAVE_SERVING

Which serving engine adapter to use. Default: ollama.

Value	Status
ollama	Shipped — default. Local HTTP API at BIGWAVE_OLLAMA_URL.
vllm	Shipped. GPU-bound; the installer auto-starts vllm serve in the background when --serving=vllm is selected.
llama_cpp	Shipped. HTTP API at BIGWAVE_LLAMA_CPP_URL.
sglang	Shipped. HTTP API at BIGWAVE_SGLANG_URL.
tgi	Shipped. Hugging Face Text Generation Inference at BIGWAVE_TGI_URL.

BIGWAVE_OLLAMA_URL

Where the Ollama HTTP API lives. Default: http://ollama:11434 (the Compose service name) or http://127.0.0.1:11434 (bare-metal).

BIGWAVE_VLLM_URL

When serving=vllm. Default: http://vllm:8000 (Compose) or http://127.0.0.1:8000 (bare-metal).

BIGWAVE_VLLM_API_KEY

Optional bearer token presented to vLLM (vLLM accepts an API key when started with --api-key). Default: empty.

BIGWAVE_LLAMA_CPP_URL

When serving=llama_cpp. Where the llama.cpp server's OpenAI-compatible HTTP API lives. Default: http://llama-cpp:8080 (Compose) or http://127.0.0.1:8080 (bare-metal).

BIGWAVE_SGLANG_URL

When serving=sglang. Where the SGLang server's OpenAI-compatible HTTP API lives. Default: http://sglang:30000 (Compose) or http://127.0.0.1:30000 (bare-metal).

BIGWAVE_TGI_URL

When serving=tgi. Where the Hugging Face Text Generation Inference (TGI) server lives. Default: http://tgi:8080 (Compose) or http://127.0.0.1:8080 (bare-metal).

BIGWAVE_MODEL

The default model loaded at startup. Default: llama3.2:3b.

Pre-pull this in Ollama before booting Bigwave, or the API process will fail to load it. The installer handles pulling automatically.

BIGWAVE_FALLBACK_MODELS

Comma-separated list of models the firstparty gateway falls back to when the primary fails pre-stream. Default: empty (no fallback).

BIGWAVE_FALLBACK_MODELS=qwen2.5:7b,llama3.2:3b

The chain runs in order; mid-stream errors propagate (no silent re-streaming on a different model). See BIGWAVE_LITELLM_FALLBACK_MODELS for the litellm equivalent.

BIGWAVE_DRAIN_TIMEOUT_S

Max seconds ReplicaManager.activate waits for in-flight requests to drain before the swap. Default: 30.0. A drain timeout returns HTTP 409 from the activate route; the old handle stays live.

Storage

BIGWAVE_STORAGE_URL

SQLAlchemy async DSN. Default: sqlite+aiosqlite:///./bigwave.db.

# SQLite (default, dev)
BIGWAVE_STORAGE_URL=sqlite+aiosqlite:///./bigwave.db

# Postgres (production)
BIGWAVE_STORAGE_URL=postgresql+asyncpg://bigwave:<pw>@db.internal:5432/bigwave

Postgres support requires pip install 'bigwave[postgres]'. The storage backend accepts postgres://, postgresql://, postgresql+asyncpg://, and postgres+asyncpg://.

Switching backends is a fresh-install operation (see optional-by-design adapters).

BIGWAVE_DATA_DIR

Where datasets + LanceDB collections live on disk. Default: ./data. Must be writable.

Vector store

BIGWAVE_VECTOR

Which VectorStore adapter to use. Default: lancedb.

Value	Behaviour
lancedb	Embedded file-backed under BIGWAVE_DATA_DIR/lancedb. No service to run. Default.
pgvector	Postgres + the vector extension. Reuses the same database as BIGWAVE_STORAGE_URL (which must be a Postgres URL — Settings.__post_init__ rejects the combination otherwise).
qdrant	Separate Qdrant service over REST. Connection knobs below.
milvus	Separate Milvus service (self-hosted or Zilliz Cloud). Connection knobs below.

BIGWAVE_QDRANT_URL

When vector=qdrant. Default: http://localhost:6333.

BIGWAVE_QDRANT_API_KEY

Optional API key for Qdrant Cloud / secured self-hosted. Sent as the api-key HTTP header. Default: empty.

BIGWAVE_PGVECTOR_SCHEMA

When vector=pgvector. Dedicated Postgres schema for the vector tables. Default: bigwave_vec.

Schema isolation (rather than a name prefix) means DROP SCHEMA bigwave_vec CASCADE wipes the vector store without touching application tables, and list_collections() cannot accidentally pick up application tables that happen to share a prefix. Each collection lands as <schema>.<collection> with a HNSW index on the embedding column.

The name must be a valid Postgres identifier ([A-Za-z_][A-Za-z0-9_]*); the adapter rejects anything else at construction time.

BIGWAVE_MILVUS_URI

When vector=milvus. Milvus connection URI. Default: http://localhost:19530. Accepts http://host:port, https://host:port (Zilliz Cloud), or unix:///path/to/sock.

BIGWAVE_MILVUS_TOKEN

Optional Milvus API token (Zilliz Cloud) or username:password pair for self-hosted clusters with auth enabled. Sent on the client connection. Default: empty.

Auth

BIGWAVE_AUTH

Which auth adapter to use. Default: bearer.

Value	Behaviour
bearer	Compares Authorization: Bearer ... to BIGWAVE_ADMIN_TOKEN; one synthetic principal in workspace default.
proxy_headers	Trusts identity headers from peers in BIGWAVE_TRUSTED_PROXY_CIDRS. Header names default to oauth2-proxy convention but each is overridable below.

BIGWAVE_TRUSTED_PROXY_CIDRS

Comma-separated CIDRs that Bigwave will trust the identity headers from when auth=proxy_headers. Default: empty (which makes proxy_headers reject every request — you must set this before enabling).

BIGWAVE_AUTH=proxy_headers
BIGWAVE_TRUSTED_PROXY_CIDRS=10.0.0.0/8,127.0.0.1/32

BIGWAVE_PROXY_EMAIL_HEADER

When auth=proxy_headers. Header name carrying the authenticated email. Default: X-Auth-Request-Email (oauth2-proxy convention).

BIGWAVE_PROXY_USER_HEADER

When auth=proxy_headers. Header name carrying the principal's username. Default: X-Auth-Request-User.

BIGWAVE_PROXY_GROUPS_HEADER

When auth=proxy_headers. Header name carrying the comma-separated groups list. Default: X-Auth-Request-Groups.

Rate limiting

BIGWAVE_RATE_LIMIT_RPS_PER_WORKSPACE

Steady-state token-bucket refill rate per workspace. Default: 0.0 (disabled). Any positive value enables the limiter; bucket capacity is rps * burst_multiplier.

BIGWAVE_RATE_LIMIT_RPS_PER_WORKSPACE=10  # 10 chats/sec sustained

BIGWAVE_RATE_LIMIT_BURST_MULTIPLIER

Multiplier on rps for burst capacity. Default: 2.0. So rps=10, burst=2 gives a 20-token bucket — bursts up to 20 then falls back to 10/sec.

Install mode (ADR 0019)

BIGWAVE_SERVE_STATIC_WEB

Default: unset (false). When truthy (1, true, yes, on), the API process mounts apps/web/dist/ at / and serves the built Web UI bundle directly. Used by bare-metal installs that don't run a separate reverse proxy.

BIGWAVE_SERVE_STATIC_WEB=true

When false (default), the API only serves /v1/*, /admin/*, and /healthz; operators front the bundle with their own reverse proxy or run npm run dev for development.

Observability

BIGWAVE_OBSERVABILITY

Default: stdout.

Value	Behaviour
stdout	NDJSON to BIGWAVE_LOG_DIR/inference.ndjson. Zero deps.
phoenix	OTLP-HTTP to a Phoenix sidecar. Requires pip install 'bigwave[observability-phoenix]'.
langfuse	OTLP-HTTP to Langfuse Cloud or self-hosted. Requires pip install 'bigwave[observability-langfuse]'.

BIGWAVE_LOG_DIR

Where stdout-backend writes its NDJSON. Default: ./logs. Must be writable.

BIGWAVE_PHOENIX_ENDPOINT

When observability=phoenix. Default: http://localhost:6006/v1/traces.

BIGWAVE_PHOENIX_PROJECT

OpenInference project name. Default: bigwave.

BIGWAVE_LANGFUSE_HOST

When observability=langfuse. Cloud or self-hosted base URL. Default: https://cloud.langfuse.com.

BIGWAVE_LANGFUSE_PUBLIC_KEY

When observability=langfuse. Public half of the Langfuse OTLP Basic-auth pair. No default — required.

BIGWAVE_LANGFUSE_SECRET_KEY

When observability=langfuse. Secret half of the OTLP Basic-auth pair. No default — required.

BIGWAVE_LANGFUSE_PROJECT

Langfuse project name surfaced in trace metadata. Default: bigwave.

Guardrails

BIGWAVE_GUARDRAILS

Default guardrail provider used by the chat input/output check seam. Per-workspace policies set via /admin/guardrails/policy still override. Default: off.

Value	Behaviour
off	NoopGuardrailProvider — every workspace passes through unless a per-workspace policy is set.
dsl	DSLGuardrailProvider loaded from BIGWAVE_GUARDRAILS_POLICY_FILE. Falls back to noop if the file is missing or malformed (logged).
llama_guard	LlamaGuardGuardrailProvider. Loads BIGWAVE_GUARDRAILS_LLAMA_GUARD_MODEL into the same engine as chat. Falls back to noop on engine errors (fail_open=true).

BIGWAVE_GUARDRAILS_POLICY_FILE

When guardrails=dsl. Path to a YAML policy file with the DSL shape (regex / deny / allow / rewrite / warn). No default — must be set or DSL falls back to noop.

BIGWAVE_GUARDRAILS_LLAMA_GUARD_MODEL

When guardrails=llama_guard. Engine-specific tag (e.g. llama-guard3:1b for Ollama). Default: llama-guard3:1b.

The model handle is loaded at lifespan startup and unloaded on shutdown so dev --reload cycles don't accumulate Ollama slots / vLLM GPU memory.

Channels

BIGWAVE_CHANNEL_SECRET_KEY

Required to enable /admin/channels (channel-binding CRUD) and the auto-bind described below. Used as a Fernet key for encrypting credentials at rest.

BIGWAVE_CHANNEL_SECRET_KEY=$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')

When unset, the channel admin routes return 503 and the lifespan's auto-bind is silently skipped (logged at WARNING).

BIGWAVE_CHANNELS

Comma-separated list of channels the API lifespan auto-binds at startup when their secrets are set. Default: empty.

Value	Auto-bind requires
telegram	BIGWAVE_TELEGRAM_BOT_TOKEN set
slack	Both BIGWAVE_SLACK_BOT_TOKEN and BIGWAVE_SLACK_SIGNING_SECRET set

The installer's --channels= flag accepts web too, but web is silently dropped from this list — the Web UI is built into the FastAPI app, not a poller adapter.

Auto-bind is idempotent across restarts: the lifespan reuses an existing (workspace=default, protocol=…) binding instead of inserting duplicate rows. Per-workspace bindings created via /admin/channels are independent and unaffected.

BIGWAVE_TELEGRAM_BOT_TOKEN

When telegram is in BIGWAVE_CHANNELS. The bot token from @BotFather. Stored encrypted via Fernet at first boot.

BIGWAVE_SLACK_BOT_TOKEN

When slack is in BIGWAVE_CHANNELS. Slack bot user OAuth token (starts with xoxb-). Stored encrypted via Fernet at first boot.

BIGWAVE_SLACK_SIGNING_SECRET

When slack is in BIGWAVE_CHANNELS. Used to verify inbound webhook signatures. Stored encrypted via Fernet at first boot.

Training

BIGWAVE_TRAINING

Default: unsloth. Shipped backends: unsloth (default), axolotl, llama_factory, raw_peft_trl (raw Hugging Face PEFT + TRL).

BIGWAVE_TRAINING_WORKDIR

Per-job training workdir on disk. Default: ./.bigwave/training.

Job runner

BIGWAVE_RUNNER

Default: noop. Background-job runner selection:

Value	Behaviour
noop	No background runner started; for tests + default installs that don't need async jobs.
arq	Arq with a Redis broker; lifespan starts an ArqRedis pool and exposes an ArqJobRunner on app.state.job_runner.

BIGWAVE_REDIS_URL

When runner=arq. Default: redis://localhost:6379.

Retrieval

BIGWAVE_EMBED_MODEL

Embedding model. Default: falls back to BIGWAVE_MODEL. Set this explicitly when you want a separate (smaller, faster) embedding model.

BIGWAVE_EMBED_MODEL=nomic-embed-text:v1.5

Quick reference table

Var	Default	Required
BIGWAVE_ADMIN_TOKEN	—	Yes
BIGWAVE_GATEWAY	firstparty	No
BIGWAVE_LITELLM_DEFAULT_MODEL	(uses BIGWAVE_MODEL)	No
BIGWAVE_LITELLM_FALLBACK_MODELS	``	No
BIGWAVE_SERVING	ollama	No
BIGWAVE_OLLAMA_URL	http://ollama:11434	No
BIGWAVE_VLLM_URL	http://vllm:8000	When serving=vllm
BIGWAVE_VLLM_API_KEY	``	No
BIGWAVE_LLAMA_CPP_URL	http://llama-cpp:8080	When serving=llama_cpp
BIGWAVE_SGLANG_URL	http://sglang:30000	When serving=sglang
BIGWAVE_TGI_URL	http://tgi:8080	When serving=tgi
BIGWAVE_MODEL	llama3.2:3b	No
BIGWAVE_FALLBACK_MODELS	``	No
BIGWAVE_DRAIN_TIMEOUT_S	30.0	No
BIGWAVE_STORAGE_URL	sqlite+aiosqlite:///./bigwave.db	No
BIGWAVE_DATA_DIR	./data	No
BIGWAVE_VECTOR	lancedb	No
BIGWAVE_QDRANT_URL	http://localhost:6333	When vector=qdrant
BIGWAVE_QDRANT_API_KEY	``	No
BIGWAVE_PGVECTOR_SCHEMA	bigwave_vec	No
BIGWAVE_MILVUS_URI	http://localhost:19530	When vector=milvus
BIGWAVE_MILVUS_TOKEN	``	No
BIGWAVE_AUTH	bearer	No
BIGWAVE_TRUSTED_PROXY_CIDRS	``	When auth=proxy_headers
BIGWAVE_PROXY_EMAIL_HEADER	X-Auth-Request-Email	No
BIGWAVE_PROXY_USER_HEADER	X-Auth-Request-User	No
BIGWAVE_PROXY_GROUPS_HEADER	X-Auth-Request-Groups	No
BIGWAVE_RATE_LIMIT_RPS_PER_WORKSPACE	0.0	No
BIGWAVE_RATE_LIMIT_BURST_MULTIPLIER	2.0	No
BIGWAVE_LOG_DIR	./logs	No
BIGWAVE_OBSERVABILITY	stdout	No
BIGWAVE_PHOENIX_ENDPOINT	http://localhost:6006/v1/traces	No
BIGWAVE_PHOENIX_PROJECT	bigwave	No
BIGWAVE_LANGFUSE_HOST	https://cloud.langfuse.com	No
BIGWAVE_LANGFUSE_PUBLIC_KEY	—	When observability=langfuse
BIGWAVE_LANGFUSE_SECRET_KEY	—	When observability=langfuse
BIGWAVE_LANGFUSE_PROJECT	bigwave	No
BIGWAVE_GUARDRAILS	off	No
BIGWAVE_GUARDRAILS_POLICY_FILE	—	When guardrails=dsl
BIGWAVE_GUARDRAILS_LLAMA_GUARD_MODEL	llama-guard3:1b	No
BIGWAVE_CHANNEL_SECRET_KEY	—	Yes for /admin/channels + auto-bind
BIGWAVE_CHANNELS	``	No
BIGWAVE_TELEGRAM_BOT_TOKEN	—	When telegram in BIGWAVE_CHANNELS
BIGWAVE_SLACK_BOT_TOKEN	—	When slack in BIGWAVE_CHANNELS
BIGWAVE_SLACK_SIGNING_SECRET	—	When slack in BIGWAVE_CHANNELS
BIGWAVE_TRAINING	unsloth	No
BIGWAVE_TRAINING_WORKDIR	./.bigwave/training	No
BIGWAVE_RUNNER	noop	No
BIGWAVE_REDIS_URL	redis://localhost:6379	When runner=arq
BIGWAVE_EMBED_MODEL	(uses BIGWAVE_MODEL)	No
BIGWAVE_SERVE_STATIC_WEB	false	No