Skip to content

Environment Variable Reference ​

All environment variables are validated at startup using Zod. If a required variable is missing or invalid, the server refuses to start with a clear error message.

Configuration is loaded from a .env file (via dotenv) and then validated against the schema in src/env.ts.

Runtime: @odp/api needs Node.js 22 or later (engines.node >=22.0.0; the AI SDK v7 requires it). The Docker image is node:22-alpine.

Booleans accept true/false, 1/0, yes/no, on/off in any case (or a boolean: cast prefix); empty means "use the default". Any other value refuses to start — it is never silently read as false (or true).


Database ​

VariableDefaultRequiredDescription
DB_CLIENTpgNoDatabase driver: pg, mysql, mysql2, sqlite3, better-sqlite3
DB_HOSTlocalhostNoDatabase host
DB_PORT5432NoDatabase port
DB_DATABASEcmsNoDatabase name
DB_USERodp_userNoDatabase user
DB_PASSWORD``NoDatabase password
DB_SSLfalseNoEnable SSL connection
DB_SSL_REJECT_UNAUTHORIZEDtrueNoReject DB server certs that fail verification (set false to allow self-signed)
DB_SSL_CA—NoPath to a CA bundle (PEM) used to verify the DB server cert — e.g. AWS RDS global-bundle.pem
DB_POOL_MIN0NoMin connection pool size
DB_POOL_MAX10NoMax connection pool size
DB_FILENAME—NoSQLite database file path (SQLite only)
DB_LOG_QUERIESfalseNoLog all raw SQL queries to console (requires LOG_LEVEL=debug)

MySQL notes ​

  • Time zone. The MySQL connection runs in UTC: mysql2 reads and writes a JS Date as UTC (timezone: 'Z') and every pooled session runs SET time_zone = '+00:00', so a Date written by the API and a CURRENT_TIMESTAMP column default agree whatever the zone of the Node process or of the server.
  • ISO-8601 strings. MySQL refuses an ISO string such as 2026-11-03T02:36:00.666Z in a DATETIME / TIMESTAMP column, and the API writes timestamps in that form. On MySQL only, the database client rewrites every query value that is exactly YYYY-MM-DDTHH:MM:SS[.f]Z, with 0 to 6 fraction digits, to YYYY-MM-DD HH:MM:SS[.f] (src/database/mysql-client.ts). A value with an offset (+07:00, which MySQL 8.4 reads itself), without the Z, with 7 or more fraction digits, or with any text around it is sent unchanged, and so is a JSON column value (it is sent as one JSON string). Risk: on MySQL, a text field whose whole value matches that form is stored as YYYY-MM-DD HH:MM:SS[.f] (for example 2026-01-01T00:00:00Z as 2026-01-01 00:00:00). PostgreSQL and SQLite store it as sent.
  • Fractional seconds. A DATETIME / TIMESTAMP column created without a precision keeps whole seconds, and MySQL rounds the milliseconds (.666 → next second) instead of cutting them.

Server ​

VariableDefaultRequiredDescription
HOST0.0.0.0NoBind address
PORT6688NoHTTP port
PUBLIC_URLhttp://localhost:6688NoPublicly accessible base URL
TRUST_PROXY127.0.0.1/8,::1/128,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7NoFastify trustProxy — an IP/CIDR list (comma-separated) or true/false. A hop count (1) is refused at boot: Fastify ≥ 5.12 treats it as trusting no proxy. The default trusts proxies by address (loopback + RFC1918 + ULA) instead of by hop count, so request.ip resolves to the real client IP regardless of how many internal proxy tiers sit in front of the API and whether traffic arrives via the BFF or a direct app call. With a public CDN as the outermost hop, append its ranges; to tighten, replace the list with the exact proxy subnet (e.g. 10.0.1.0/24). Never true in production
SECRET—YesJWT signing secret. Known placeholder values (e.g. the old compose default) are refused; NODE_ENV=production requires ≥ 32 characters. Generate with openssl rand -hex 32
SECRET_ALLOW_WEAKfalseNoDeprecated escape hatch: lets an existing production deploy boot with a SECRET < 32 characters until it is rotated. Never allows a known placeholder
ACCESS_TOKEN_TTL15mNoAccess token lifetime (e.g., 15m, 1h)
REFRESH_TOKEN_TTL7dNoRefresh token lifetime (e.g., 7d, 30d)
SESSION_COOKIE_ENABLEDtrueNoEnable session cookie mode
SESSION_COOKIE_NAMEodp_session_tokenNoCookie name for session tokens
LOG_LEVELinfoNotrace, debug, info, warn, error, fatal
LOG_STYLEraw in production, else prettyNopretty (colored output) or raw (JSON)
LOG_FILE—NoPath to write logs to a file
LOG_REQUESTStrueNoLog each HTTP request
LOG_REQUEST_BODYoffNoAdd the sanitized request body (res.request_body, one JSON string) to the request completed line: off, errors (status >= 400 only) or all. Credential and email keys (password, token, secret, otp, api_key, email, ...) are masked. Recommended in production: errors
LOG_REQUEST_BODY_MAX4096NoMaximum length (characters) of res.request_body; longer bodies end with …[truncated]
OTEL_EXPORTER_OTLP_ENDPOINT—NoOTel Collector base URL (e.g. http://otel-collector:4318). Set → both loggers also push logs over OTLP (/v1/logs is appended); unset → stdout/file only. Protocol via OTEL_EXPORTER_OTLP_PROTOCOL (default http/protobuf). See service/api/src/modules/telemetry/README.md
OTEL_SERVICE_NAMEodp-apiNoservice.name resource attribute of exported logs
EXTENSION_LOG_LEVELS—NoLog level per extension, id=level comma-separated, * for every other extension (e.g. my-ext=debug,*=info). Wins over the manifest's odp-extension.logLevel. Never below LOG_LEVEL (to get debug from one extension, lower LOG_LEVEL too). An invalid entry is ignored with one boot warning. See Extension Guardrails §7
EXTENSION_LOG_RATE50Noctx.logger lines per second per extension (sustained). Over the cap a line is dropped (stdout too) and one extension log rate cap hit warn line is written per 10 s window; counter odp_extension_log_dropped_total{extension_id}
EXTENSION_LOG_BURST500NoBucket size of that cap (lines an extension can write at once)
EXTENSION_AUDIT_RATE20Noctx.audit.event() calls per second per extension (burst 100); refused calls count too. Over the cap an event is dropped and one extension audit rate cap hit warn line is written per 10 s window
EXTENSION_AUDIT_CRITICAL_PER_MIN10Nocritical audit events per minute per extension; more are sent as warning with details.downgraded: "critical_rate". 0 = an extension never sends critical
MAX_PAYLOAD_SIZE1mbNoMaximum request body size
ROOT_REDIRECT/server/infoNoWhere / redirects to
NODE_ENVdevelopmentNodevelopment, production, test

CORS ​

VariableDefaultDescription
CORS_ENABLEDtrueEnable CORS headers
CORS_ORIGIN*Allowed origins (comma-separated or *)
CORS_METHODSGET,POST,PATCH,DELETEAllowed HTTP methods
CORS_ALLOWED_HEADERSContent-Type,AuthorizationAllowed request headers
CORS_EXPOSED_HEADERSContent-RangeExposed response headers
CORS_CREDENTIALSfalseAllow credentials. true requires an explicit CORS_ORIGIN list — boot fails with *
CORS_MAX_AGE18000Preflight cache duration (seconds)

Workflow ​

VariableDefaultDescription
WORKFLOW_STRICT_NODESfalseWhen true, activating a workflow with an unknown node/action type (or a failing validateConfig) is rejected. When false, unknown nodes are allowed and park to waiting at runtime

Cache ​

VariableDefaultDescription
CACHE_ENABLEDfalseEnable response caching
CACHE_TTL5mCache entry lifetime
CACHE_STOREmemoryBackend: memory or redis
CACHE_AUTO_PURGEfalseAuto-invalidate on mutations
CACHE_SCHEMAtrueCache database schema
CACHE_SYSTEM_TTL10mSystem cache TTL
CACHE_NAMESPACEodpCache key prefix
CACHE_STATUS_HEADERx-cache-statusResponse header for cache status
CACHE_VALUE_MAX_SIZE1mbMaximum cacheable response size

Redis ​

VariableDefaultDescription
REDIS_ENABLEDfalseUse Redis for cache and sessions
REDIS_HOST127.0.0.1Redis host
REDIS_PORT6379Redis port
REDIS_PASSWORD``Redis password
REDIS_DB0Redis database index
REDIS_TLSfalseEnable TLS (managed Redis with in-transit encryption / rediss://)
REDIS_TLS_REJECT_UNAUTHORIZEDtrueReject Redis server certs that fail verification (set false to allow self-signed)
REDIS_TLS_CA—Path to a CA bundle (PEM) to verify the Redis server cert (self-signed / private CA)

Storage & Files ​

VariableDefaultDescription
STORAGE_LOCAL_ROOT./uploadsLocal file storage directory
FILES_MAX_UPLOAD_SIZE10mbMaximum upload size per file
FILES_MIME_TYPE_ALLOW_LIST*Allowed MIME types (* = all, or comma-separated list)
FILES_MAX_UPLOAD_CONCURRENCY5Max simultaneous file uploads

Image Transformation (Assets) ​

VariableDefaultDescription
ASSETS_TRANSFORM_IMAGE_MAX_DIMENSION6000Max output width or height (pixels)
ASSETS_TRANSFORM_MAX_CONCURRENT25Max concurrent image transforms
ASSETS_TRANSFORM_TIMEOUT30Transform timeout (seconds)
ASSETS_CACHE_TTL30mTransformed asset cache TTL
ASSETS_INVALID_IMAGE_SENSITIVITY_LEVELwarningHow to handle corrupt images: none, truncated, error, warning

Email ​

VariableDefaultDescription
EMAIL_FROMno-reply@example.comDefault sender address
EMAIL_TRANSPORTsmtpTransport: smtp, ses, sendmail
EMAIL_SMTP_HOSTlocalhostSMTP server host
EMAIL_SMTP_PORT587SMTP port
EMAIL_SMTP_USER``SMTP username
EMAIL_SMTP_PASSWORD``SMTP password
EMAIL_SMTP_SECUREfalseEnable TLS/SSL

Rate Limiting ​

VariableDefaultDescription
RATE_LIMITER_ENABLEDtrueMaster toggle for every limiter (global, per-IP, per-principal, login, email)
RATE_LIMITER_STOREmemoryStore: memory or redis
RATE_LIMITER_POINTS50Anonymous per-IP requests per window (also charged to requests whose token matches no auth strategy)
RATE_LIMITER_DURATION1Per-IP window duration (seconds)
RATE_LIMITER_GLOBAL_ENABLEDtrueEnable global (all-IP) rate limit
RATE_LIMITER_GLOBAL_POINTS1000Global requests per window
RATE_LIMITER_GLOBAL_DURATION1Global window duration (seconds)
RATE_LIMITER_USER_POINTS300Per-user requests per window (roles without service_account)
RATE_LIMITER_USER_DURATION60Per-user window duration (seconds)
RATE_LIMITER_SERVICE_POINTS10000Per-service-account requests per window (roles flagged service_account, e.g. the BFF appApi token — one bucket per service user)
RATE_LIMITER_SERVICE_DURATION60Service-account window duration (seconds)
RATE_LIMITER_LOGIN_POINTS10POST /auth/login attempts per client IP per window
RATE_LIMITER_LOGIN_DURATION60Login window duration (seconds)
RATE_LIMITER_ASSETS_POINTS300Anonymous /assets/* requests per IP per window (media Range streaming)
RATE_LIMITER_ASSETS_DURATION1Assets window duration (seconds)

Authentication Throttling ​

VariableDefaultDescription
LOGIN_THROTTLE_DELAY1sInitial delay after failed login
LOGIN_THROTTLE_MAX_DELAY30sMaximum backoff delay

WebAuthn / Passkey ​

VariableDefaultDescription
WEBAUTHN_RP_ID—Relying Party ID (domain passkeys bind to). Must never change once credentials are registered. Derives from PUBLIC_URL when unset — set explicitly in split deploys
WEBAUTHN_RP_NAMEODPHuman-readable Relying Party name shown during registration
WEBAUTHN_ORIGIN—Comma-separated browser origins allowed to complete ceremonies (e.g. https://admin.example.com)

Security Events ​

VariableDefaultDescription
SECURITY_EVENTS_ENABLEDtrueRecord security events (login attempts, permission failures, etc.)

SSRF Protection ​

VariableDefaultDescription
SSRF_PROTECTION_ENABLEDtrueBlock outbound requests to private/internal addresses
SSRF_ALLOWED_HOSTS``Comma-separated hosts exempted from SSRF protection

Audit Hash Chain ​

VariableDefaultDescription
AUDIT_HASH_ENABLEDfalseEnable tamper-evident hash chaining for audit records
AUDIT_HMAC_KEY``HMAC key used to sign the audit hash chain
AUDIT_VERIFY_SCHEDULE0 * * * *Cron schedule for the audit chain verification job

AI Engine ​

VariableDefaultDescription
ASSISTANT_RATE_LIMIT_PER_MIN20Per-user Agentic quota per minute; below 1 means no limit.
ASSISTANT_INGEST_COLLECTIONS``Comma-separated collections to live-sync to the knowledge backend on item create/update/delete; empty disables the listeners
ASSISTANT_LLM_PROVIDERopenai-compatibleLLM provider of the env path (no ai_integrations row): openai-compatible, openai, anthropic or google. A native value is used only when ASSISTANT_LLM_BASE_URL is that vendor's host, else the endpoint is called as OpenAI-compatible. Any other value fails the call.
ASSISTANT_LLM_BASE_URLhttp://localhost:20128/v1LLM API base URL (OpenAI-compatible)
ASSISTANT_LLM_MODELgpt-4o-miniDefault LLM model
ASSISTANT_LLM_API_KEY—LLM API key
KAOS_BASE_URLhttp://localhost:7071KAOS RAG store base URL
KAOS_API_KEY—KAOS API key
KAOS_IDENTITY_IDodpKAOS service identity ID
KAOS_IDENTITY_KINDserviceKAOS identity kind
KAOS_IDENTITY_SCOPESknowledge:jobs:write,knowledge:readKAOS identity scopes (comma-separated)
AI_INGEST_MAX_CONTENT_BYTES15728640Max bytes per ingested document (sits just under KAOS's 16MB body limit)
AI_MOCK_RETRIEVALfalseDev-only synthetic retrieval so a RAG flow completes without real KAOS data. Hard-disabled in production
AI_HISTORY_TOKEN_BUDGET3000Conversation-memory history budget (tokens); crossing 50% triggers a rolling summary
AI_ENABLE_CODE_NODEfalseGate for the code flow node (Function() eval — NOT a sandbox)

Configuration Drift Detection ​

VariableDefaultDescription
DRIFT_DETECTION_ENABLEDfalseEnable configuration drift detection
DRIFT_CHECK_SCHEDULE*/5 * * * *Cron schedule for the drift check job

WebSocket ​

VariableDefaultDescription
WEBSOCKETS_ENABLEDfalseEnable WebSocket support (opt-in — set true to turn on; the /websocket route is not registered when disabled)
WEBSOCKETS_HEARTBEAT_ENABLEDtrueEnable ping/pong heartbeat (only applies when WEBSOCKETS_ENABLED=true)
WEBSOCKETS_HEARTBEAT_PERIOD30Heartbeat interval (seconds)
WEBSOCKETS_REST_ENABLEDtrueEnable REST-over-WebSocket
WEBSOCKETS_REST_AUTHhandshakeAuth mode: public, handshake, strict
WEBSOCKETS_GRAPHQL_ENABLEDtrueEnable GraphQL over WebSocket
WEBSOCKETS_GRAPHQL_AUTHhandshakeAuth mode: public, handshake, strict

Extensions ​

VariableDefaultDescription
EXTENSIONS_PATH./extensionsDirectory to load extensions from
EXTENSIONS_MUST_LOAD``Comma-separated list of extensions that must load (server fails if missing)

TUS Resumable Upload ​

VariableDefaultDescription
TUS_UPLOAD_EXPIRATION10mExpiry for incomplete TUS uploads
TUS_CLEANUP_SCHEDULE0 */6 * * *Cron schedule for TUS cleanup job

Miscellaneous ​

VariableDefaultDescription
MIGRATIONS_PATH``Path to custom migration files
PRESSURE_ENABLEDtrueEnable server load shedding
METRICS_ENABLEDfalseExpose Prometheus metrics endpoint
METRICS_TOKEN``Scrape credential (min 16 chars) for GET /server/metrics, sent as header x-metrics-token — Prometheus then needs no admin token. Unset: admin only
METRICS_NAME_PREFIXodp_Prometheus metric name prefix
USER_INVITE_TOKEN_TTL7dInvite token lifetime
EMAIL_VERIFICATION_TOKEN_TTL7dEmail verification token lifetime
REGISTER_STALL_TIME750Minimum response time (ms) for registration to mask user enumeration
USER_REGISTER_URL_ALLOW_LIST``Comma-separated URLs allowed as registration verification redirect targets
PASSWORD_RESET_URL_ALLOW_LIST``Comma-separated base URLs a client may pass as reset_url to POST /auth/password/request (e.g. the admin webapp origin). PUBLIC_URL is always allowed; any other reset_url is rejected with 400
QUERYSTRING_MAX_PARSE_DEPTH10Max nesting depth for query string parsing
QUERY_ACCESS_TOKENallWhere ?access_token= authenticates: all (every route), assets (/assets/* + /websocket only), none. Tokens are masked in logs either way
ENABLE_APP_PERMISSIONStrueApp-module permissions (workflow, notify, versions, MCP access). Off with any false value (false, 0, off, no)
IMPERSONATION_TTL15mLifetime of an impersonation token
MAX_IMPERSONATION_SESSIONS3Concurrent impersonation sessions per impersonator (min 1)
MAX_RELATIONAL_DEPTH10Max depth of relational paths in fields / filter / sort / deep (min 2)

Example .env ​

env
# Required
SECRET=<output of: openssl rand -hex 32>

# Database
DB_CLIENT=pg
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=odp
DB_USER=odp_user
DB_PASSWORD=odp_password

# Server
PORT=6688
PUBLIC_URL=https://api.example.com
LOG_LEVEL=info
LOG_STYLE=raw

# Cache (Redis)
CACHE_ENABLED=true
CACHE_STORE=redis
REDIS_ENABLED=true
REDIS_HOST=redis
REDIS_PORT=6379

# Email
EMAIL_FROM=no-reply@example.com
EMAIL_TRANSPORT=smtp
EMAIL_SMTP_HOST=smtp.example.com
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=smtp-user
EMAIL_SMTP_PASSWORD=smtp-password
EMAIL_SMTP_SECURE=true

# Storage
STORAGE_LOCAL_ROOT=/data/uploads
FILES_MAX_UPLOAD_SIZE=50mb

# Security
RATE_LIMITER_ENABLED=true
SESSION_COOKIE_ENABLED=true

ODP Internal API Documentation