# How Logto Is Configured Using Environment Variables: Complete Developer Guide

> Learn how to configure Logto using environment variables. This guide covers database connections, endpoints, and feature flags for your core service and CLI.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: how-to-guide
- Published: 2026-07-06

---

**Logto is configured entirely through environment variables that are read, validated, and normalized by the `GlobalValues` singleton in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts), exposing typed properties for database connections, endpoints, and feature flags across the core service and CLI.**

Logto, the open-source identity infrastructure maintained by logto-io/logto, uses environment variables as the sole mechanism for runtime configuration. Instead of static configuration files, the platform leverages a centralized TypeScript wrapper called `GlobalValues` to ingest `process.env` variables (or Vite's `import.meta.env` in front-end packages), ensuring type safety and consistent validation throughout the monorepo.

## The GlobalValues Configuration Layer

At the heart of Logto's configuration system sits the **`GlobalValues`** class located in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts). This singleton acts as a thin normalization layer that reads raw environment variables, performs transformations such as boolean conversion, and exposes them as strongly-typed properties. By centralizing variable access through this wrapper, Logto ensures that configuration errors are caught early and that defaults are applied consistently across the core service, CLI utilities, and administrative console.

## Essential Environment Variables

Logto recognizes dozens of environment variables that control everything from database connectivity to HTTPS certificate paths. Below are the critical configuration values organized by functional area.

### Database Configuration

The **`DB_URL`** variable is required for both the core service and CLI, specifying the PostgreSQL connection string (e.g., `postgres://postgres:p0stgr3s@localhost:5432/logto`). For operation tuning, **`DATABASE_STATEMENT_TIMEOUT`** sets the maximum duration in milliseconds for database statements to execute before being terminated.

### Public Endpoints

Define how users and administrators reach your Logto deployment:

- **`ENDPOINT`**: The public-facing Logto URL used by front-ends to discover the OIDC discovery document (e.g., `https://demo.logto.app/`).
- **`ADMIN_ENDPOINT`**: The dedicated URL for administrative API access (e.g., `https://demo.logto.app/admin/`).

### Authentication and Security

For machine-to-machine communication, **`LOGTO_AUTH`** accepts credentials in the format `<app-id>:<app-secret>`. Transport layer security is configured via **`HTTPS_CERT_PATH`** and **`HTTPS_KEY_PATH`**, which point to the TLS certificate and key files when running Logto over HTTPS. The **`CASE_SENSITIVE_USERNAME`** boolean flag enforces case-sensitivity rules for usernames.

### Development and Testing

Toggle experimental functionality with **`DEV_FEATURES_ENABLED`**, which exposes "dev-only" features like experimental UI components across all packages. The **`INTEGRATION_TEST`** flag marks execution contexts for test suites. For local development, **`LOGTO_EXPERIENCE_URI`** specifies the base URL of the sign-in experience server (typically `http://localhost:3001`).

### Analytics and Telemetry

Integrate with PostHog using **`POSTHOG_PUBLIC_KEY`** and **`POSTHOG_PUBLIC_HOST`**. The **`LOGTO_OSS_SURVEY_ENDPOINT`** variable configures the URL for displaying the Open-Source Survey banner in the console, as implemented in [`packages/core/src/middleware/koa-security-headers.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/middleware/koa-security-headers.ts).

## Accessing Configuration in Code

When building extensions or working within the Logto monorepo, import the `globalValues` singleton to access normalized configuration:

```typescript
import { globalValues } from '@logto/shared/src/node/env';

// Access the database connection string
const dbUrl = globalValues.databaseUrl; // Maps to process.env.DB_URL

// Check feature flags
if (globalValues.devFeaturesEnabled) {
  // Execute experimental code path
}

```

This pattern ensures that your code receives properly typed values rather than raw strings, eliminating manual parsing of booleans or numbers from `process.env`.

## Configuring the CLI and Core Service

For local development or production deployment, export variables in your shell or use an `.env` file (see `.env.example` in the repository root for the canonical reference):

```bash
export DB_URL="postgres://postgres:p0stgr3s@localhost:5432/logto"
export ENDPOINT="https://demo.logto.app/"
export ADMIN_ENDPOINT="https://demo.logto.app/admin/"
export LOGTO_AUTH="123456:abcdef"
export DEV_FEATURES_ENABLED="true"
export NODE_ENV="production"

# Start the CLI

pnpm cli start

```

The CLI utilities in [`packages/cli/src/utils.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/utils.ts) consume these variables via `process.env`, while the console front-end receives them through Vite's `import.meta.env` mapping as defined in [`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts).

## Key Source Files for Configuration

Understanding where configuration logic resides helps when debugging or extending Logto:

- **[`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts)**: Centralized definition, parsing, and export of all environment variables as typed properties.
- **`.env.example`**: Canonical reference file listing every supported variable with documentation and default values.
- **[`packages/cli/src/utils.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/utils.ts)**: Demonstrates CLI consumption of `DB_URL`, `LOGTO_AUTH`, and endpoint variables.
- **[`packages/tunnel/src/commands/tunnel/utils.ts`](https://github.com/logto-io/logto/blob/main/packages/tunnel/src/commands/tunnel/utils.ts)**: Handles tunnel-specific variables including `LOGTO_ENDPOINT` and `LOGTO_EXPERIENCE_URI`.
- **[`packages/core/src/middleware/koa-security-headers.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/middleware/koa-security-headers.ts)**: Uses `LOGTO_OSS_SURVEY_ENDPOINT` to inject survey banners.

## Summary

- Logto uses **environment variables exclusively** for runtime configuration, managed through the `GlobalValues` singleton.
- **`DB_URL`**, **`ENDPOINT`**, and **`ADMIN_ENDPOINT`** are required for basic operation.
- Boolean variables like **`DEV_FEATURES_ENABLED`** and **`CASE_SENSITIVE_USERNAME`** undergo automatic type conversion in `GlobalValues`.
- Access configuration programmatically via `import { globalValues } from '@logto/shared/src/node/env'`.
- Reference `.env.example` for the complete list of supported variables and their formats.

## Frequently Asked Questions

### What is the main file that handles environment variables in Logto?

The **[`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts)** file contains the `GlobalValues` class, which serves as the single source of truth for reading, validating, and typing all environment variables. This singleton normalizes raw `process.env` values and exposes them as strongly-typed properties used throughout the core service, CLI, and front-end packages.

### How do I configure Logto to use HTTPS?

Set the **`HTTPS_CERT_PATH`** and **`HTTPS_KEY_PATH`** environment variables to point to your TLS certificate and private key files before starting the service. These paths are read by the core service during initialization to enable encrypted communications on the configured endpoints.

### Can I use a .env file for Logto configuration?

Yes. Logto supports `.env` files in development and production environments. The repository root contains an **`.env.example`** file that documents every supported variable with default values and descriptions. Copy this file to `.env` and populate it with your specific values; Node.js will automatically load these when the process starts.

### What environment variables are required to run Logto?

At minimum, you must provide **`DB_URL`** for PostgreSQL connectivity and **`ENDPOINT`** for the public-facing URL. If you are running administrative operations or the CLI, **`ADMIN_ENDPOINT`** and **`LOGTO_AUTH`** (for machine-to-machine credentials) are also necessary. All other variables have sensible defaults defined in `GlobalValues`.