> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ragen.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Complete Environment Variable Reference for Ragen AI
> Configure every aspect of Ragen AI through environment variables — storage, encryption, mail, models, auth, and feature flags, all in one place.
Environment variables are the primary configuration mechanism for Ragen AI. The web application, API server, and background worker all read their configuration from the process environment at boot, and the same variable names apply whether you are running locally with a `.env` file or deploying to a container orchestrator. A **required** variable is required only once you have chosen a provider that needs it; everything else has a working default in code.
**Looking for a specific variable?** The
[configuration reference](/configuration/environment-reference) lists every
one, generated from the schemas each application validates against at boot —
so it cannot disagree with the code. This page explains the *choices*: which
provider to pick, and what each one implies.
## Provider Settings
One variable selects an implementation for each provider, and that choice determines which additional variables you must set.
Choose your storage backend with `STORAGE_PROVIDER`, which defaults to `local`.
Files are written to the container filesystem. `STORAGE_LOCAL_PATH` defaults to `./data/storage`, so nothing is mandatory — but every process that touches files needs access to the same mounted volume.
```bash theme={null}
STORAGE_PROVIDER=local
STORAGE_LOCAL_PATH=/data/storage
```
Any S3-compatible object store. Leave `S3_ENDPOINT_URL` unset for real AWS S3, or set it to point at Cloudflare R2, Scaleway, MinIO, or Ceph.
```bash theme={null}
STORAGE_PROVIDER=s3
S3_BUCKET_NAME=my-ragen-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
# S3_ENDPOINT_URL=https://... # omit for real AWS S3
```
Choose your encryption backend with `ENCRYPTION_PROVIDER`. When unset, Ragen auto-detects from whichever credentials are present, in priority order: Scaleway → KMS → local.
Encryption is opt-in and off by default in local development. On staging and production (`TARGET_ENV=staging` or `production`), a deployment with no encryption provider configured will refuse to start unless you set `ALLOW_UNENCRYPTED=1` — which is logged as a critical security event. Set a provider before going live.
Scaleway Key Manager. Reuses `SCW_API_KEY`, so one IAM key covers both encryption and Scaleway-hosted model/rerank calls.
```bash theme={null}
ENCRYPTION_PROVIDER=scaleway
SCW_KEY_MANAGER_KEY_ID=11111111-2222-3333-4444-555555555555
SCW_KEY_MANAGER_REGION=fr-par
SCW_API_KEY=your-scaleway-api-key
```
AWS Key Management Service.
```bash theme={null}
ENCRYPTION_PROVIDER=kms
AWS_KMS_KEY_ID=arn:aws:kms:eu-central-1:123456789:key/your-key-id
AWS_DEFAULT_REGION=eu-central-1
```
A master key held in the environment. Use this for on-premise deployments without an external KMS.
```bash theme={null}
ENCRYPTION_PROVIDER=local
# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_MASTER_KEY=a1b2c3...
```
Post-retrieval reranking sharpens search results. Choose the provider with `RERANK_PROVIDER`. Reranking is off by default — enable it with `FEATURE_FLAG_RERANKING=1`.
Scaleway's `/v1/rerank` endpoint. Reuses `SCW_API_KEY`.
```bash theme={null}
RERANK_PROVIDER=scaleway
SCW_API_BASE=https://api.scaleway.ai/YOUR_PROJECT_ID/v1
SCW_API_KEY=your-scaleway-api-key
RERANK_MODEL=qwen3-embedding-8b
```
Cohere Rerank v3.5, over an endpoint speaking Cohere's rerank **HTTP shape**: Cohere's own API, a gateway in front of it, a proxy you run that has the model registered, or a local server that exposes a Cohere-compatible `/rerank` (vLLM does).
Not Bedrock. Bedrock's rerank is an AWS API with SigV4 signing, not a Cohere-shaped endpoint a base URL and a bearer key can reach — the proxy used to do that translation, and it is gone.
```bash theme={null}
RERANK_PROVIDER=cohere
RERANK_COHERE_BASE_URL=https://your-endpoint
RERANK_COHERE_API_KEY=your-key
RERANK_MODEL=cohere-rerank-v3-5
```
`RERANK_COHERE_BASE_URL` has **no default**. Selecting this variant without it reranks nothing, and does so quietly: an unreachable reranker degrades to "no reranking" rather than erroring. Set it deliberately and confirm reranking is actually happening.
Choose your mail transport with `MAIL_PROVIDER`. When unset, Ragen auto-detects: `RESEND_API_KEY` wins, then `SMTP_HOST`, then `console` outside production.
Resend transactional email.
```bash theme={null}
MAIL_PROVIDER=resend
RESEND_API_KEY=re_...
```
Any SMTP relay. Only `SMTP_HOST` is required; `SMTP_PORT` defaults to 587. Authentication is configured only when `SMTP_USER` is set.
```bash theme={null}
MAIL_PROVIDER=smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=sender@example.com
SMTP_PASS=your-password
```
Writes the mail message (including links) to the application log instead of sending it. Ideal for local development and for production installations where an administrator creates every account manually.
No additional variables required.
```bash theme={null}
MAIL_PROVIDER=console
```
## Core Settings
Database, vector store, Redis and Temporal are listed
with their config fields and requiredness in the
[configuration reference](/configuration/environment-reference), which is
generated from the schemas the applications validate against at boot. They are
not repeated here, because a second copy is a copy that goes wrong: the last
hand-written reference called `S3_ENDPOINT_URL` required when it is optional,
omitted `S3_SESSION_TOKEN`, and described an encryption failure backwards.
One that decides how model calls are made is worth naming here, and is covered
properly in [Model gateway](/configuration/model-gateway):
| Variable | Required | Default | Description |
| ----------------- | -------- | ------- | --------------------------------------------- |
| `LLM_ROUTES_PATH` | Optional | — | Route table to use instead of the shipped one |
There is no variable selecting a gateway mode any more: Ragen calls providers
itself, and an external gateway is a route rather than a setting.
## Auth Settings
| Variable | Required | Description |
| --------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | **Required** | Secret key for Better Auth session signing. Generate with `openssl rand -hex 32`. |
| `BETTER_AUTH_URL` | **Required** | Public URL of this installation (e.g. `https://app.example.com`). Used in all outbound email links. |
| `SESSION_AUTH_SECRET` | **Required** | Shared secret for issuing short-lived session tokens between the web app and the API service. Must be set to the same value in both services. |
| `SECRET_KEY` | **Required** | Key used to encrypt organisation API keys stored in the database. Generate with `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`. |
Generate secret values with:
```bash theme={null}
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
## Feature Flags
Feature flags control optional capabilities. Most are off by default and enabled by setting them to `1`; `FEATURE_FLAG_DOC_SUMMARIES` is the exception — it defaults on and is disabled by setting it to `0`.
| Variable | Default | Description |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FEATURE_FLAG_RERANKING` | Off | Enable post-retrieval reranking. Also requires provider credentials (`SCW_API_BASE` + `SCW_API_KEY` for Scaleway, or AWS credentials for Cohere). |
| `FEATURE_FLAG_PII_MASKING` | — | **Kill switch only.** Masking is on when `PRESIDIO_ANALYZER_URL` and `PRESIDIO_ANONYMIZER_URL` are both set; `0` turns it off on a configured deployment. Fails closed on error — unmasked PII never reaches the LLM. See [PII masking](/security/pii-masking). |
| `FEATURE_FLAG_DOC_SUMMARIES` | **On** | Generate AI summaries when documents are ingested. Uses `SUMMARY_MODEL`. Disable by setting to `0`. |
| `DOCLING_STRICT` | Off | Fail the ingest job instead of falling back to a legacy PDF loader that sends documents to an external model. Set to `1` for air-gapped deployments. |