Configuration

Configuring Options for OpenLIT

This guide covers all the available environment variables to fine-tune OpenLIT according to your needs.

Environment variables

INIT_DB_HOST · required

Sets the host address of the ClickHouse server for OpenLIT to connect

Example:

export INIT_DB_HOST=127.0.0.1

INIT_DB_PORT · required

Sets the port on which ClickHouse listens

Example:

export INIT_DB_PORT=8123

INIT_DB_DATABASE · required

Sets the name of the database in Clickhouse to be used by OpenLIT

Example:

export INIT_DB_DATABASE=default

INIT_DB_USERNAME · required

Sets the username for authenticating with ClickHouse

Example:

export INIT_DB_USERNAME=default

INIT_DB_PASSWORD · required

Sets the password for authenticating with ClickHouse

Example:

export INIT_DB_PASSWORD=default

SQLITE_DATABASE_URL · required

Sets the location where SQLITE data is stored.

Example:

export SQLITE_DATABASE_URL=file:/app/client/data/data.db

OAuth authentication variables

For detailed OAuth setup instructions, see the OAuth Authentication Setup guide.

NEXTAUTH_URL

Sets the canonical URL of your site for NextAuth.js authentication

Example:

export NEXTAUTH_URL=http://localhost:3000

NEXTAUTH_SECRET

Used to encrypt the NextAuth.js JWT tokens and email verification hashes

Example:

export NEXTAUTH_SECRET=your-secret-here

Generate with: openssl rand -base64 32

GOOGLE_CLIENT_ID

Google OAuth client ID for Google sign-in integration

Example:

export GOOGLE_CLIENT_ID=your-google-client-id

GOOGLE_CLIENT_SECRET

Google OAuth client secret for Google sign-in integration

Example:

export GOOGLE_CLIENT_SECRET=your-google-client-secret

GITHUB_CLIENT_ID

GitHub OAuth client ID for GitHub sign-in integration

Example:

export GITHUB_CLIENT_ID=your-github-client-id

GITHUB_CLIENT_SECRET

GitHub OAuth client secret for GitHub sign-in integration

Example:

export GITHUB_CLIENT_SECRET=your-github-client-secret

Server variables

PORT

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):

PORT=3000

DOCKER_PORT

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:

export DOCKER_PORT=3000

API_URL

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:

export API_URL=https://openlit.internal.example.com

OPENLIT_EDITION

Sets which OpenLIT build is running. Defaults to oss if unset.

Example:

export OPENLIT_EDITION=oss

Agents variables

Tune the background job that materializes the Agents page’s call graphs and versions from trace data.

AGENTS_MATERIALIZE_SCHEDULE

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:

export AGENTS_MATERIALIZE_SCHEDULE="* * * * *"

AGENTS_MATERIALIZE_MAX_PER_TICK

Maximum number of agents materialized per scheduled run. Defaults to 100.

Example:

export AGENTS_MATERIALIZE_MAX_PER_TICK=100

AGENTS_MATERIALIZE_PARALLEL

Maximum number of agents materialized concurrently per run. Defaults to 4.

Example:

export AGENTS_MATERIALIZE_PARALLEL=4

AGENTS_LOG_LEVEL

Log level for the Agents materialization job (debug, info, warn, error). Defaults to info.

Example:

export AGENTS_LOG_LEVEL=info

AGENTS_LOG_STACK

Set to false to omit stack traces from Agents materialization error logs. Defaults to including them.

Example:

export AGENTS_LOG_STACK=false

Telemetry variables

See Anonymous Telemetry for what OpenLIT’s own usage telemetry collects and why.

TELEMETRY_ENABLED

Set to false to disable OpenLIT’s anonymous usage telemetry, including the daily instance snapshot.

Example:

export TELEMETRY_ENABLED=false

TELEMETRY_SNAPSHOT_SCHEDULE

Cron schedule for the daily anonymous instance telemetry snapshot. Defaults to 17 3 * * *.

Example:

export TELEMETRY_SNAPSHOT_SCHEDULE="17 3 * * *"

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.

CRON_JOB_SECRET

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:

export CRON_JOB_SECRET=your-cron-secret

OPENLIT_REQUIRE_ORG_FILTER

Set to true to enforce organisation-scoped isolation on coding-agent telemetry queries in multi-organisation deployments.

Example:

export OPENLIT_REQUIRE_ORG_FILTER=true

OPENLIT_VAULT_ENCRYPTION_KEY

Secret used to encrypt Vault values at rest with AES-256-GCM. If this is not set, OpenLIT falls back to 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:

openssl rand -base64 32

Example:

export OPENLIT_VAULT_ENCRYPTION_KEY=your-vault-encryption-key

OPENLIT_ALLOWED_CORS_ORIGINS

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:

export OPENLIT_ALLOWED_CORS_ORIGINS=https://app.example.com,https://admin.example.com

OPENLIT_ALLOWED_ORIGINS

Backward-compatible alias for OPENLIT_ALLOWED_CORS_ORIGINS.

Example:

export OPENLIT_ALLOWED_ORIGINS=https://app.example.com

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 .env file in the src/client/ directory for development:

   src/client/.env
   

   This file is automatically loaded by Next.js during development.

2. Docker Compose .env

   Create a .env file in the same directory as your docker-compose.yml file:

   # In the root directory with docker-compose.yml
   .env
   

   This file is automatically loaded by Docker Compose.

3. Development Docker Compose .env

   For development Docker setup, create a .env file alongside src/dev-docker-compose.yml:

   # In the src/ directory with dev-docker-compose.yml
   src/.env
   

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

# Database Configuration
INIT_DB_HOST="127.0.0.1"
INIT_DB_PORT="8123"
INIT_DB_DATABASE="default"
INIT_DB_USERNAME="default"
INIT_DB_PASSWORD="OPENLIT"
SQLITE_DATABASE_URL="file:/app/client/data/data.db"

# NextAuth Configuration (Optional)
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-here"

# OAuth Providers (Optional)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Server Configuration (Optional)
# PORT is for Docker Compose; use DOCKER_PORT instead for Kubernetes or a raw container run
PORT="3000"
API_URL="http://localhost:3000"

# Agents Materialization (Optional)
AGENTS_MATERIALIZE_SCHEDULE="* * * * *"

# Telemetry (Optional)
TELEMETRY_ENABLED="true"

# Security Configuration (Optional)
OPENLIT_VAULT_ENCRYPTION_KEY="your-vault-encryption-key"
OPENLIT_ALLOWED_CORS_ORIGINS="https://app.example.com,https://admin.example.com"
CRON_JOB_SECRET="your-cron-secret"

---

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