> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openlit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configuring Options for OpenLIT

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

## Environment variables

<ResponseField name="INIT_DB_HOST" required>
  Sets the host address of the ClickHouse server for OpenLIT to connect

  **Example**:

  ```yaml theme={null}
  export INIT_DB_HOST=127.0.0.1
  ```
</ResponseField>

<ResponseField name="INIT_DB_PORT" required>
  Sets the port on which ClickHouse listens

  **Example**:

  ```yaml theme={null}
  export INIT_DB_PORT=8123
  ```
</ResponseField>

<ResponseField name="INIT_DB_DATABASE" required>
  Sets the name of the database in Clickhouse to be used by OpenLIT

  **Example**:

  ```yaml theme={null}
  export INIT_DB_DATABASE=default
  ```
</ResponseField>

<ResponseField name="INIT_DB_USERNAME" required>
  Sets the username for authenticating with ClickHouse

  **Example**:

  ```yaml theme={null}
  export INIT_DB_USERNAME=default
  ```
</ResponseField>

<ResponseField name="INIT_DB_PASSWORD" required>
  Sets the password for authenticating with ClickHouse

  **Example**:

  ```yaml theme={null}
  export INIT_DB_PASSWORD=default
  ```
</ResponseField>

<ResponseField name="SQLITE_DATABASE_URL" required>
  Sets the location where SQLITE data is stored.

  **Example**:

  ```yaml theme={null}
  export SQLITE_DATABASE_URL=file:/app/client/data/data.db
  ```
</ResponseField>

## OAuth authentication variables

<Note>
  For detailed OAuth setup instructions, see the [OAuth Authentication Setup](/latest/openlit/oauth) guide.
</Note>

<ResponseField name="NEXTAUTH_URL">
  Sets the canonical URL of your site for NextAuth.js authentication

  **Example**:

  ```yaml theme={null}
  export NEXTAUTH_URL=http://localhost:3000
  ```
</ResponseField>

<ResponseField name="NEXTAUTH_SECRET">
  Used to encrypt the NextAuth.js JWT tokens and email verification hashes

  **Example**:

  ```yaml theme={null}
  export NEXTAUTH_SECRET=your-secret-here
  ```

  **Generate with**: `openssl rand -base64 32`
</ResponseField>

<ResponseField name="GOOGLE_CLIENT_ID">
  Google OAuth client ID for Google sign-in integration

  **Example**:

  ```yaml theme={null}
  export GOOGLE_CLIENT_ID=your-google-client-id
  ```
</ResponseField>

<ResponseField name="GOOGLE_CLIENT_SECRET">
  Google OAuth client secret for Google sign-in integration

  **Example**:

  ```yaml theme={null}
  export GOOGLE_CLIENT_SECRET=your-google-client-secret
  ```
</ResponseField>

<ResponseField name="GITHUB_CLIENT_ID">
  GitHub OAuth client ID for GitHub sign-in integration

  **Example**:

  ```yaml theme={null}
  export GITHUB_CLIENT_ID=your-github-client-id
  ```
</ResponseField>

<ResponseField name="GITHUB_CLIENT_SECRET">
  GitHub OAuth client secret for GitHub sign-in integration

  **Example**:

  ```yaml theme={null}
  export GITHUB_CLIENT_SECRET=your-github-client-secret
  ```
</ResponseField>

## Server variables

<ResponseField name="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`):

  ```yaml theme={null}
  PORT=3000
  ```
</ResponseField>

<ResponseField name="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**:

  ```yaml theme={null}
  export DOCKER_PORT=3000
  ```
</ResponseField>

<ResponseField name="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**:

  ```yaml theme={null}
  export API_URL=https://openlit.internal.example.com
  ```
</ResponseField>

<ResponseField name="OPENLIT_EDITION">
  Sets which OpenLIT build is running. Defaults to `oss` if unset.

  **Example**:

  ```yaml theme={null}
  export OPENLIT_EDITION=oss
  ```
</ResponseField>

## Agents variables

Tune the background job that materializes the [Agents](/latest/openlit/observability/agents/overview) page's call graphs and versions from trace data.

<ResponseField name="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**:

  ```yaml theme={null}
  export AGENTS_MATERIALIZE_SCHEDULE="* * * * *"
  ```
</ResponseField>

<ResponseField name="AGENTS_MATERIALIZE_MAX_PER_TICK">
  Maximum number of agents materialized per scheduled run. Defaults to `100`.

  **Example**:

  ```yaml theme={null}
  export AGENTS_MATERIALIZE_MAX_PER_TICK=100
  ```
</ResponseField>

<ResponseField name="AGENTS_MATERIALIZE_PARALLEL">
  Maximum number of agents materialized concurrently per run. Defaults to `4`.

  **Example**:

  ```yaml theme={null}
  export AGENTS_MATERIALIZE_PARALLEL=4
  ```
</ResponseField>

<ResponseField name="AGENTS_LOG_LEVEL">
  Log level for the Agents materialization job (`debug`, `info`, `warn`, `error`). Defaults to `info`.

  **Example**:

  ```yaml theme={null}
  export AGENTS_LOG_LEVEL=info
  ```
</ResponseField>

<ResponseField name="AGENTS_LOG_STACK">
  Set to `false` to omit stack traces from Agents materialization error logs. Defaults to including them.

  **Example**:

  ```yaml theme={null}
  export AGENTS_LOG_STACK=false
  ```
</ResponseField>

## Telemetry variables

<Note>
  See [Anonymous Telemetry](/latest/openlit/developer-resources/anonymous-telemetry) for what OpenLIT's own usage telemetry collects and why.
</Note>

<ResponseField name="TELEMETRY_ENABLED">
  Set to `false` to disable OpenLIT's anonymous usage telemetry, including the daily instance snapshot.

  **Example**:

  ```yaml theme={null}
  export TELEMETRY_ENABLED=false
  ```
</ResponseField>

<ResponseField name="TELEMETRY_SNAPSHOT_SCHEDULE">
  Cron schedule for the daily anonymous instance telemetry snapshot. Defaults to `17 3 * * *`.

  **Example**:

  ```yaml theme={null}
  export TELEMETRY_SNAPSHOT_SCHEDULE="17 3 * * *"
  ```
</ResponseField>

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

<ResponseField name="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**:

  ```yaml theme={null}
  export CRON_JOB_SECRET=your-cron-secret
  ```
</ResponseField>

<ResponseField name="OPENLIT_REQUIRE_ORG_FILTER">
  Set to `true` to enforce organisation-scoped isolation on coding-agent telemetry queries in multi-organisation deployments.

  **Example**:

  ```yaml theme={null}
  export OPENLIT_REQUIRE_ORG_FILTER=true
  ```
</ResponseField>

<ResponseField name="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**:

  ```bash theme={null}
  openssl rand -base64 32
  ```

  **Example**:

  ```yaml theme={null}
  export OPENLIT_VAULT_ENCRYPTION_KEY=your-vault-encryption-key
  ```
</ResponseField>

<ResponseField name="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**:

  ```yaml theme={null}
  export OPENLIT_ALLOWED_CORS_ORIGINS=https://app.example.com,https://admin.example.com
  ```
</ResponseField>

<ResponseField name="OPENLIT_ALLOWED_ORIGINS">
  Backward-compatible alias for `OPENLIT_ALLOWED_CORS_ORIGINS`.

  **Example**:

  ```yaml theme={null}
  export OPENLIT_ALLOWED_ORIGINS=https://app.example.com
  ```
</ResponseField>

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

## Environment file placement

Environment variables can be configured in multiple ways depending on your deployment method:

### Development setup

<Steps>
  <Step title="Client-side .env">
    Create a `.env` file in the `src/client/` directory for development:

    ```bash theme={null}
    src/client/.env
    ```

    This file is automatically loaded by Next.js during development.
  </Step>

  <Step title="Docker Compose .env">
    Create a `.env` file in the same directory as your `docker-compose.yml` file:

    ```bash theme={null}
    # In the root directory with docker-compose.yml
    .env
    ```

    This file is automatically loaded by Docker Compose.
  </Step>

  <Step title="Development Docker Compose .env">
    For development Docker setup, create a `.env` file alongside `src/dev-docker-compose.yml`:

    ```bash theme={null}
    # In the src/ directory with dev-docker-compose.yml
    src/.env
    ```
  </Step>
</Steps>

### 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.example .env theme={null}
# 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"
```

***

<CardGroup cols={3}>
  <Card title="Create a dashboard" href="/latest/openlit/dashboards/overview" icon="grid">
    Create custom visualizations with flexible widgets, queries, and real-time AI monitoring
  </Card>

  <Card title="Manage prompts" href="/latest/openlit/prompts-experiments/prompt-hub/overview" icon="message">
    Version, deploy, and collaborate on prompts with centralized management and tracking
  </Card>

  <Card title="LLM playground" href="/latest/openlit/prompts-experiments/openground/overview" icon="flask">
    Compare cost, duration, and response tokens across different LLMs to find the most efficient model
  </Card>
</CardGroup>