How Logto Is Configured Using Environment Variables: Complete Developer Guide

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

Accessing Configuration in Code

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

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

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

Key Source Files for Configuration

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

• 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: Demonstrates CLI consumption of DB_URL, LOGTO_AUTH, and endpoint variables.
• 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: 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}