Complete Environment Variable Reference for Ragen AI

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 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.

Storage
Encryption
Reranker
Mail

Choose your storage backend with STORAGE_PROVIDER, which defaults to local.

local (default)
s3

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.

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.

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
kms
local

Scaleway Key Manager. Reuses SCW_API_KEY, so one IAM key covers both encryption and Scaleway-hosted model/rerank calls.

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.

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.

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 (default)
cohere

Scaleway’s /v1/rerank endpoint. Reuses SCW_API_KEY.

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.

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
smtp
console

Resend transactional email.

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.

MAIL_PROVIDER=smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=[email protected]
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.

MAIL_PROVIDER=console

Core Settings

Database, vector store, Redis and Temporal are listed with their config fields and requiredness in the configuration 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:

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:

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.
`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.

Get Started

Core Concepts

Configuration

Integrations

Security

Resources

Complete Environment Variable Reference for Ragen AI

Provider Settings

Core Settings

Auth Settings

Feature Flags

​Provider Settings

​Core Settings

​Auth Settings

​Feature Flags

Provider Settings

Core Settings

Auth Settings

Feature Flags