Cortex's configuration lives in the .env file at the repository root, created by copying .env.example. The latter is the reference: every variable is commented there. Compose reads the .env file on the host each time it runs; an automated check only verifies that every variable Compose uses is declared in it with the same default. This page covers the variables an administrator needs, by theme. Defaults are those of .env.example.
Where a value takes effect
Docker Compose reads .env on the host. A container receives a variable only if docker-compose.yml lists it in its environment: block. The gateway variables shown here are listed, except those whose role starts with "Host-side only": for those, editing .env changes nothing in the containers, which keep the code's built-in default. They only serve a process started directly on the host (pnpm gateway:dev, an administration command), or once added to the service's environment: block. The AI engine has no Compose service: it is started with docker run -e …, and its variables (CONTEXT_SIGNING_PUBLIC_KEY, DLP2_*, RAG_EMBEDDING_*) are passed to its container, not through .env. The pnpm --filter gateway … commands (tenant:provision, audit:verify…) do not read .env: give them the values inline or export them in the shell. Only the pnpm migration:run shortcut at the repository root reads .env. After a change, relaunch the service concerned with docker compose up -d <service>, which recreates the container and re-reads the values.
Database and keys
Variable
Role
Default
DATABASE_URL
The gateway's runtime identity (the cortex_gateway role). Required for an external database.
empty: Compose builds the URL of the bundled database
MIGRATION_DATABASE_URL
Host-side only. Owner identity (cortex_owner) for migrations and administration commands.
not set: falls back to DATABASE_URL
KMS_LOCAL_KEK
Key-encryption key (32 bytes, base64). Required; the same value for the gateway and for the commands that load it (tenant:provision, user:create, destination:create, tenant:erase, audit:verify; migration:run does not need it).
empty: Compose substitutes a published development key
Tenant and authentication
Variable
Role
Default
AUTH_TENANT_SLUG
Tenant served by this deployment. The gateway refuses to start without it.
cortex
AUTH_LOCAL_ENABLED
Local accounts (email and password). Only the exact value true enables them. Startup is refused if false with neither OIDC nor SAML.
true
GATEWAY_PUBLIC_URL
Public origin of the gateway, from which SSO redirect addresses derive. Behind the web proxy: the web origin followed by /api/gateway.
OIDC. The issuer URL enables it; the client id and secret then become required.
empty
SAML_IDP_SSO_URL, SAML_IDP_CERT
SAML. The URL enables it; the certificate then becomes required.
empty
SAML_SP_ENTITY_ID
Service provider identifier, identical to the one registered at the identity provider.
cortex-gateway
SESSION_TTL_HOURS
Host-side only. Session lifetime, in hours (positive number).
8
Language
Variable
Role
Default
DEFAULT_LOCALE
Interface language: en or fr-CA (any other value gives en). Also the default language of a tenant created by tenant:provision, if the variable is exported in the shell or --locale is passed.
en
AI engine
Variable
Role
Default
AI_ENGINE_ENABLED
Enables calls to the engine. Disabled, the gateway never calls it.
false
AI_ENGINE_URL
Origin of the engine (scheme, host, port; no path). Required when enabled.
empty
CONTEXT_SIGNING_PRIVATE_KEY
Ed25519 private key (PKCS#8 DER in base64) that signs the header sent to the engine. Required when enabled.
empty
CONTEXT_SIGNING_PUBLIC_KEY
Host-side only. The matching public key, read by the engine.
empty
AI_ENGINE_DLP_TIMEOUT_MS
Timeout of a DLP 1.5 detection call. Past it, the request continues on DLP 1 alone.
3000
AI_ENGINE_DLP2_TIMEOUT_MS
Timeout of a local-model detection call (DLP 2), with the same degradation.
20000
AI_ENGINE_RAG_TIMEOUT_MS
Timeout of a document extraction or an embedding batch.
120000
DLP2_BACKEND_URL, DLP2_MODEL
Host-side only. OpenAI-compatible server (with its /v1 prefix) and model for DLP 2 detection; set together.
empty
Knowledge base
The knowledge base needs the AI engine and an embedding server. If the engine is disabled in the configuration, uploads are refused; they wait in the queue only while the engine is not answering or no embedding model is declared.
Variable
Role
Default
RAG_MAX_DOCUMENT_BYTES
Maximum size of a document, in bytes (1024 to 33554432).
10485760
RAG_MAX_DOCUMENTS
Maximum number of documents per tenant, in any status.
1000
RAG_TOP_K
Maximum number of passages injected into a turn (1 to 20).
5
RAG_MIN_SIMILARITY
Minimum similarity of a passage (0 to 1); depends on the model.
0.3
RAG_INGEST_INTERVAL_MS
Pace of document processing. 0 disables it: documents stay "Uploaded".
5000
RAG_INGEST_TIMEOUT_MS
Past it, a document stuck in processing is taken up again.
600000
RAG_EMBEDDING_DIM
Host-side only. Vector width, frozen once migrations have run.
1024
RAG_EMBEDDING_BACKEND_URL, RAG_EMBEDDING_MODEL
Host-side only. OpenAI-compatible embedding server (with /v1) and model; set together. That server receives document text in clear.
empty
Cache, web search, costs and routing
Variable
Role
Default
CACHE_ENABLED
Enables the exact-response cache (DLP still applies).
false
CACHE_BACKEND
memory or redis.
memory
CACHE_TTL_SECONDS
Maximum lifetime of an entry; the tenant's retention also caps it.
3600
CACHE_MAX_ENTRIES
Maximum number of entries in the in-memory cache.
1000
CACHE_EXCLUDED_ROLES
Roles excluded from the cache, comma-separated.
empty
REDIS_URL
Read only with redis, for example redis://redis:6379.
empty
WEB_SEARCH_ENABLED
Enables web search; the next four then become load-bearing.
false
WEB_SEARCH_ENGINE
searxng or brave.
searxng
WEB_SEARCH_BASE_URL
Address of the engine, which the gateway container must be able to reach. Required when enabled.
empty
WEB_SEARCH_API_KEY
Engine key; required with brave.
empty
WEB_SEARCH_TIMEOUT_MS
Timeout of one search (1 to 120000).
10000
FINOPS_LOCAL_COST_PER_MTOK
Flat rate per million tokens for local destinations.
Default limits (requests and tokens per minute) for virtual keys without their own.
empty: no limit
ROUTING_RETRY_MAX_ATTEMPTS
Attempts per destination, the first included (1 to 5).
2
ROUTING_RETRY_BASE_MS
Base delay before a retry, doubled at each attempt (0 to 5000).
200
Retention
Variable
Role
Default
RETENTION_PURGE_INTERVAL_MS
Host-side only. Interval between two scheduled purges. A zero, negative or non-numeric value schedules no purge, without any message.
3600000
For every other variable (ports, logging, METRICS_TOKEN, provider timeouts, the DLP rewriter window, the first administrator), see .env.example in the repository.
