ClickHouse connection at runtime is a Database Config, not a live env lookup.
INIT_DB_* variables seed the first Database Config when OpenLIT is first set up. Day-2 host, password, or environment changes belong in Organisation → Database Config and Connectors. See also Connectors and Signal routing.ClickHouse bootstrap (INIT_DB_*)
Used once at seed/install time to create the default Database Config. After that, the UI (and APIs under /api/db-config) own the connection.
Environment variables
required
Seed-only: host address written into the default Database Config on first setup. Not read on every request after the config exists.Example:
required
Seed-only: ClickHouse HTTP port for the default Database Config (commonly
8123).Example:required
Seed-only: ClickHouse database name for the default Database Config.Example:
required
Seed-only: username stored on the default Database Config.Example:
required
Seed-only: password stored on the default Database Config. Rotate later via the Database Config UI, not by relying on this env var alone.Example:
required
Sets the location where SQLITE data is stored.Example:
OAuth authentication variables
For detailed OAuth setup instructions, see the OAuth Authentication Setup guide.
Sets the canonical URL of your site for NextAuth.js authenticationExample:
Used to encrypt the NextAuth.js JWT tokens and email verification hashesExample:Generate with:
openssl rand -base64 32Google OAuth client ID for Google sign-in integrationExample:
Google OAuth client secret for Google sign-in integrationExample:
GitHub OAuth client ID for GitHub sign-in integrationExample:
GitHub OAuth client secret for GitHub sign-in integrationExample:
Server variables
Sets the port the OpenLIT server listens on. For Docker Compose deployments, set this in the
.env file next to docker-compose.yml - Compose maps it to both the host port and the container’s internal DOCKER_PORT for you. For Kubernetes or a raw container run, set DOCKER_PORT directly instead (see below); the container’s entrypoint always derives its actual listening port from DOCKER_PORT, defaulting to 3000 if unset.Example (Docker Compose .env):Sets the port the OpenLIT container listens on internally. Only relevant for Kubernetes or a raw container run where there’s no Docker Compose translating
PORT for you.Example:Sets the base URL OpenLIT uses to call back into its own API - required by the Auto Evaluation, Auto Pricing, Agents materialization, and telemetry-snapshot cron jobs, which run as separate processes and call this URL directly. Defaults to
http://localhost:$PORT. Set this if you run behind a reverse proxy, a non-default host, or a different container/pod hostname - otherwise these background jobs will fail silently after every restart.Example:Sets which OpenLIT build is running. Defaults to
oss if unset.Example:Agents variables
Tune the background job that materializes the Agents page’s call graphs and versions from trace data.Cron schedule for the Agents materialization job. Defaults to
* * * * * (every minute); the job self-throttles when there’s no new trace data to process.Example:Maximum number of agents materialized per scheduled run. Defaults to
100.Example:Maximum number of agents materialized concurrently per run. Defaults to
4.Example:Log level for the Agents materialization job (
debug, info, warn, error). Defaults to info.Example:Set to
false to omit stack traces from Agents materialization error logs. Defaults to including them.Example:Realtime variables
Realtime evaluation powers threshold alerts. The OTLP receiver publishes each GenAI span sent with an API key to NATS JetStream, and the bundledopenlit-engine evaluates every enabled alert and records breaches, which appear under Alerts. Docker Compose includes a NATS service by default. Realtime is disabled when NATS_URL is unset.
NATS JetStream server URL. When set, the receiver publishes realtime signals and the container starts the realtime engine.Example:
NATS user for the OTLP receiver. Docker Compose uses
openlit-receiver, which assets/nats.conf only allows to publish signals and manage the signal stream. NATS_RECEIVER_TOKEN and NATS_RECEIVER_CREDS are also accepted.NATS user for the realtime engine. Docker Compose uses
openlit-engine, which can only read the signal stream. NATS_ENGINE_TOKEN and NATS_ENGINE_CREDS are also accepted. NATS_USER, NATS_PASSWORD, NATS_TOKEN, and NATS_CREDS are used as a shared fallback for both.TLS for NATS: a CA bundle, an optional client certificate and key for mutual TLS, and
NATS_TLS_REQUIRED=true to refuse plaintext connections. Use TLS whenever NATS runs outside the OpenLIT container network.Shared secret between the UI server and the realtime engine, sent as
X-OpenLIT-Engine-Secret. The Docker image generates one per install and stores it in the data volume. Outside Docker, set the same value for both processes; the engine refuses to start without it, and the internal realtime routes reject every request. It is separate from CRON_JOB_SECRET.Size cap (default 256 MiB) and retention (default
10m) of the signal stream. The oldest signals are discarded first.Engine limits: rule windows per alert (default
200), per organisation/project/environment (default 1000), and in total (default 50000), samples per window (default 5000), and findings each environment can open per minute (default 60). Excess is dropped and counted.Receiver hardening: the loopback listener for pipeline counters (default
127.0.0.1:4319, off disables), the API key cache size (default 10000), and how many rejected API keys a client IP may send (default burst 20, refilling 60 per minute) before it receives 429.Base URL the UI uses to read live spans for an alert from the engine. Defaults to
http://127.0.0.1:4330, which matches the engine inside the Docker container and scripts/dev-realtime.sh.Example:The engine’s internal HTTP listener (default
127.0.0.1:4330, which serves live spans to the UI) and the UI URL the engine reads alerts from and posts findings to (default http://127.0.0.1:3000; the Docker image sets it from the UI port). Keep ENGINE_HTTP_ADDR on loopback or a private network.How often the engine reloads alerts (default
10s), how often it evaluates every window (default 5s), and how much of the signal stream it replays on start (default 10m), as Go durations.JetStream stream name for signals (default
OPENLIT_SIGNALS). The receiver and the engine must use the same name.How long resolved threshold alert history is kept (default
30 days) and how many groups can be firing at once in each project environment (default 1000). New groups beyond that limit are not recorded.Suggested window (default
300, max 3600), minimum spans (default 20), and cooldown (default 900) in the threshold alert templates. They only change the values a new alert starts with.Personal span and resource attribute keys that realtime signals may carry. Comma-separated. Threshold alerts can filter and group by any span or resource attribute (up to 64 per span, values truncated to 256 bytes) without configuration, except keys that identify people or internal systems: any key with a
user, enduser, session, conversation, email, phone, ip, address, or path segment (such as user.id, gen_ai.conversation.id, url.path, or server.address). Those are only copied when listed here. Prompt, completion, message, and secret attributes are always ignored, and values that look like credentials are redacted.Example:Suggested thresholds in the threshold alert templates: error rate per service (default
0.25), p95 latency per model (default 30000), total tokens per model per window (default 1000000), and span-reported cost per model per window (default 25). Nothing alerts until someone creates an alert.Example:Realtime production checklist
- Set strong
NATS_RECEIVER_PASSWORDandNATS_ENGINE_PASSWORDvalues (or use NATS creds files), and keep NATS on a private network. Docker Compose does not publish NATS ports. - Enable TLS (
NATS_TLS_*) when NATS is not on the same host or container network. - Keep
OPENLIT_ENGINE_SECRETandCRON_JOB_SECRETdistinct and secret, and keepENGINE_HTTP_ADDRandOTLP_STATS_ADDRon loopback. - Set
OTLP_REQUIRE_API_KEY=trueso every span is attributed to a project. - Leave personal-data attributes out of
OPENLIT_SIGNAL_ATTRIBUTESunless rules need them.
Telemetry variables
See Anonymous Telemetry for what OpenLIT’s own usage telemetry collects and why.
Set to
false to disable OpenLIT’s anonymous usage telemetry, including the daily instance snapshot.Example:Cron schedule for the daily anonymous instance telemetry snapshot. Defaults to
17 3 * * *.Example:Security variables
OpenLIT enables stricter API protections by default, including security response headers, CSRF checks for browser session API requests, vault secret encryption, and restricted CORS for the vault secrets API.Token required to trigger internal cron-driven endpoints (Auto Evaluation, Auto Pricing, Agents materialization, telemetry snapshot). Optional for typical self-hosted installs - when unset, both the cron scripts and the endpoint check fall back to the same shared default, so scheduled jobs work out of the box with no configuration. Set it only if your instance is exposed such that an untrusted party could otherwise call these endpoints directly.Changing this takes effect on the next restart, since cron entries are re-created from the current environment on every server startup.Example:
Set to
true to enforce organisation-scoped isolation on coding-agent telemetry queries in multi-organisation deployments.Example:Secret used to encrypt Vault values at rest with AES-256-GCM. If this is not set, OpenLIT falls back to Example:
NEXTAUTH_SECRET.Use a stable, high-entropy value and keep it unchanged across restarts. Changing this value after secrets are encrypted prevents existing Vault values from being decrypted.Generate with:Comma-separated list of browser origins that are allowed to call API-key authenticated Vault secret retrieval from another domain.Configure this when a browser application hosted on a different origin needs to call
POST /api/vault/get-secrets. Server-to-server SDK or REST calls usually do not need this because they do not send a browser Origin header.Specify complete origins, including scheme and host. Do not use *.Example:Backward-compatible alias for
OPENLIT_ALLOWED_CORS_ORIGINS.Example:NEXTAUTH_URL is also treated as an allowed same-site origin for Vault CORS checks. Browser requests from other domains must be listed in OPENLIT_ALLOWED_CORS_ORIGINS or OPENLIT_ALLOWED_ORIGINS.Environment file placement
Environment variables can be configured in multiple ways depending on your deployment method:Development setup
1
Client-side .env
Create a This file is automatically loaded by Next.js during development.
.env file in the src/client/ directory for development:2
Docker Compose .env
Create a This file is automatically loaded by Docker Compose.
.env file in the same directory as your docker-compose.yml file:3
Development Docker Compose .env
For development Docker setup, create a
.env file alongside src/dev-docker-compose.yml:Production setup
For production deployments, set environment variables directly in your hosting platform or container orchestration system (Kubernetes, Docker Swarm, etc.).Applying changes at runtime
OpenLIT reads environment variables once when the server process starts - there’s no hot-reload, so a config change (editing a.env file, updating a Kubernetes Secret, etc.) only takes effect after you restart the container or process.
A restart is also all you need for the cron-driven features (Auto Evaluation, Auto Pricing, Agents materialization, telemetry snapshot): their scheduled jobs are re-created from the current environment on every startup, so there’s no separate step to “re-save” settings after changing something like API_URL, CRON_JOB_SECRET, or AGENTS_MATERIALIZE_SCHEDULE.
Sample environment file (.env)
.env
Create a dashboard
Create custom visualizations with flexible widgets, queries, and real-time AI monitoring
Manage prompts
Version, deploy, and collaborate on prompts with centralized management and tracking
LLM playground
Compare cost, duration, and response tokens across different LLMs to find the most efficient model