---
audience: developer
summary: Every `SCAIWAVE_*` environment variable. The truth lives in `app/config.py`.
title: Configuration
path: reference/configuration
status: published
---

# Configuration

All configuration is via environment variables prefixed
`SCAIWAVE_`. The authoritative source is `app/config.py`
(a Pydantic `Settings` model); this page is curated for clarity.

## Required

| Var | Example | Purpose |
|---|---|---|
| `SCAIWAVE_SERVER_NAME` | `scaiwave.example.com` | Public hostname (used for federation FQIDs, signed URL bases). |
| `SCAIWAVE_DB_URL` | `mysql+aiomysql://user:pass@host/scaiwave` | Database URL. |
| `SCAIWAVE_REDIS_URL` | `redis://host:6379/0` | Redis URL. |
| `SCAIWAVE_NATS_URL` | `nats://host:4222` | NATS URL. |

## Auth

| Var | Default | Purpose |
|---|---|---|
| `SCAIWAVE_AUTH_MODE` | `mock` (dev), `scaikey` (prod) | Which auth strategy to use. |
| `SCAIWAVE_SCAIKEY_URL` | — | ScaiKey base URL. |
| `SCAIWAVE_SCAIKEY_CLIENT_ID` | — | OAuth client id. |
| `SCAIWAVE_SCAIKEY_CLIENT_SECRET` | — | OAuth client secret. |

## ScaiGrid (AI)

| Var | Default | Purpose |
|---|---|---|
| `SCAIWAVE_SCAIGRID_URL` | — | ScaiGrid base URL. |
| `SCAIWAVE_SCAIGRID_API_KEY` | — | Static fallback key. Use per-user exchange in prod. |
| `SCAIWAVE_AI_EMBEDDING_MODEL` | `scailar-4` | Default embedding model for indexing + retrieval. |
| `SCAIWAVE_SCAIGRID_DEFAULT_MODEL` | — | Default chat model when none specified. |
| `SCAIWAVE_AI_INFERENCE_TIMEOUT` | `120` | Seconds. |

## Storage

| Var | Purpose |
|---|---|
| `SCAIWAVE_S3_ENDPOINT` | MinIO / S3 endpoint. |
| `SCAIWAVE_S3_BUCKET` | Bucket name. |
| `SCAIWAVE_S3_ACCESS_KEY` | Access key. |
| `SCAIWAVE_S3_SECRET_KEY` | Secret. |
| `SCAIWAVE_S3_REGION` | Region (for AWS). |

## Search

| Var | Default | Purpose |
|---|---|---|
| `SCAIWAVE_WEAVIATE_URL` | — | Weaviate URL. |
| `SCAIWAVE_WEAVIATE_COLLECTION` | `ScaiWaveMessages` | Messages collection name. |

## Calls

| Var | Purpose |
|---|---|
| `SCAIWAVE_LIVEKIT_URL` | LiveKit WS URL. |
| `SCAIWAVE_LIVEKIT_API_KEY` | API key. |
| `SCAIWAVE_LIVEKIT_API_SECRET` | API secret. |

## ClamAV

| Var | Purpose |
|---|---|
| `SCAIWAVE_CLAMAV_URL` | `tcp://clamav:3310`. |
| `SCAIWAVE_CLAMAV_ENABLED` | `true` / `false`. |

## ScaiDrive

| Var | Purpose |
|---|---|
| `SCAIWAVE_SCAIDRIVE_URL` | ScaiDrive base URL. |
| `SCAIWAVE_SCAIDRIVE_API_KEY` | Dev fallback (will 401 in prod; use per-user exchange). |
| `SCAIWAVE_SCAIDRIVE_DEFAULT_SHARE_ID` | Default share for backup_media calls. |

## ScaiSearch (web search plugin)

| Var | Purpose |
|---|---|
| `SCAIWAVE_SCAISEARCH_URL` | SearXNG-compatible endpoint. |
| `SCAIWAVE_SCAISEARCH_API_KEY` | Auth. |

## Operational

| Var | Default | Purpose |
|---|---|---|
| `SCAIWAVE_DEBUG` | `false` | Verbose logs + `/docs` Swagger UI. |
| `SCAIWAVE_LOG_LEVEL` | `INFO` | structlog level. |
| `SCAIWAVE_LOG_FORMAT` | `json` | `json` or `pretty`. |
| `SCAIWAVE_TRUSTED_PROXIES` | empty | Comma-separated IPs to trust `X-Forwarded-For` from. |
| `SCAIWAVE_CORS_ALLOWED_ORIGINS` | `http://localhost:5173` | Comma-separated origins. |

## Federation

| Var | Default | Purpose |
|---|---|---|
| `SCAIWAVE_FEDERATION_ENABLED` | `false` | Master switch. |
| `SCAIWAVE_FEDERATION_KEY_TTL_DAYS` | `365` | Federation key rotation period. |

## Rate limits (defaults; overridable per tenant)

| Var | Default | Purpose |
|---|---|---|
| `SCAIWAVE_RATE_MESSAGE_PER_MINUTE` | `60` | Per-participant. |
| `SCAIWAVE_RATE_API_PER_MINUTE` | `300` | Per-token. |

## Where defaults live

Anything not listed here is in `app/config.py`. To see the resolved
config of a running server:

```bash
.venv/bin/python -c "from app.config import Settings; import json; print(json.dumps(Settings().model_dump(), indent=2, default=str))"
```

(Don't run this against prod logs — it'll dump credentials.)