# Complete Guide to Logto Environment Variables: Core, CLI, and Frontend Configuration

> Master Logto environment variables for core, CLI, and frontend. Configure database connections, API endpoints, TLS, flags and integrations to streamline your Logto setup.

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

---

**Logto environment variables control database connections, API endpoints, TLS certificates, feature flags, and third-party integrations across the core server, CLI utilities, and frontend applications.**

The `logto-io/logto` repository relies on a comprehensive set of **Logto environment variables** to drive configuration across its monorepo architecture. These variables are read through `process.env` in Node.js contexts and injected into frontend builds via Vite, enabling deployment flexibility from local development to production Kubernetes clusters.

## Core Server and Database Configuration

### Database Connection (DB_URL)

The `DB_URL` variable is the most critical configuration, providing the PostgreSQL DSN for all core services. According to the source code in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts) at line 167, the system asserts this variable via `assertEnv('DB_URL')`, throwing if undefined.

```typescript
// packages/shared/src/node/env/GlobalValues.ts#L167
const dbUrl = assertEnv('DB_URL'); // Required for core startup

```

### Runtime Mode (NODE_ENV)

`NODE_ENV` determines production versus development behavior, affecting logging verbosity, security headers, and build optimization. The Jest setup file at [`packages/core/jest.setup.js`](https://github.com/logto-io/logto/blob/main/packages/core/jest.setup.js) (lines 12-14) normalizes this for testing, while [`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts) (line 47) uses it to configure build targets.

### API Endpoints (ENDPOINT and ADMIN_ENDPOINT)

- **ENDPOINT**: Base URL for the user-facing API (`https://<host>/`)
- **ADMIN_ENDPOINT**: Base URL for the administrative API

Both are defined in [`packages/core/jest.setup.js`](https://github.com/logto-io/logto/blob/main/packages/core/jest.setup.js) (lines 13-14) and utilized in CORS middleware tests at [`packages/core/src/middleware/koa-cors.test.ts`](https://github.com/logto-io/logto/blob/main/packages/core/src/middleware/koa-cors.test.ts) (lines 58-104).

### TLS Termination (HTTPS_CERT_PATH and HTTPS_KEY_PATH)

For HTTPS deployments, specify the certificate and private key paths:

```typescript
// packages/shared/src/node/env/GlobalValues.ts#L71-L72
this.httpsCertPath = process.env.HTTPS_CERT_PATH;
this.httpsKeyPath = process.env.HTTPS_KEY_PATH;

```

## Authentication and Security Settings

### OIDC Private Keys (OIDC_PRIVATE_KEYS and OIDC_PRIVATE_KEY_PATHS)

During database seeding, these variables supply OpenID Connect private keys either as direct strings or file paths. The CLI command at [`packages/cli/src/commands/database/seed/oidc-config.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/commands/database/seed/oidc-config.ts) (lines 90-91) processes these to establish initial identity provider configuration.

```typescript
// packages/cli/src/commands/database/seed/oidc-config.ts#L90-L91
const privateKeys = process.env.OIDC_PRIVATE_KEYS;
const privateKeyPaths = process.env.OIDC_PRIVATE_KEY_PATHS;

```

### Key Rotation Grace Period

`PRIVATE_KEY_ROTATION_GRACE_PERIOD` defines the overlap window when rotating OIDC keys, configured in [`packages/cli/src/commands/database/config.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/commands/database/config.ts) at line 209.

### Username Case Sensitivity

Set `CASE_SENSITIVE_USERNAME` to toggle case-sensitive login handling, defined at line 285 of [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts).

## Frontend Build and Feature Flags

### Console and Experience Configuration

Frontend applications receive environment variables through Vite's `define` injection. The Console SPA configuration at [`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts) (line 19) uses `CONSOLE_PUBLIC_URL` to set the public base path.

```typescript
// packages/console/vite.config.ts#L19
base: process.env.CONSOLE_PUBLIC_URL || '/console/',

```

### Experimental Features (DEV_FEATURES_ENABLED)

This feature-flag gate enables experimental functionality across packages:

- **Experience app**: Checked in [`packages/experience/src/constants/env.ts`](https://github.com/logto-io/logto/blob/main/packages/experience/src/constants/env.ts) (line 4)
- **Console build**: Injected at [`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts) (line 50)

Cloud-specific toggles like `IS_CLOUD` (line 47) and `PROTECTED_APP_LOCAL_DEV` (line 48) determine deployment-specific UI behaviors.

## Third-Party Service Integrations

### Analytics (PostHog and Application Insights)

PostHog configuration uses three variables defined in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts) (lines 211-213):

- `POSTHOG_PUBLIC_KEY`
- `POSTHOG_PUBLIC_HOST`
- `POSTHOG_PUBLIC_UI_HOST`

These are injected into the Console bundle at [`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts) (lines 55-58).

For Azure telemetry, `APPLICATIONINSIGHTS_CONNECTION_STRING` is read in [`packages/app-insights/src/node.ts`](https://github.com/logto-io/logto/blob/main/packages/app-insights/src/node.ts) (line 67) to conditionally initialize monitoring.

### AI Translation (OpenAI)

The translation service configuration in [`packages/translate/src/openai.ts`](https://github.com/logto-io/logto/blob/main/packages/translate/src/openai.ts) (lines 22-30) expects:

```typescript
// packages/translate/src/openai.ts#L22-L30
apiKey: process.env.OPENAI_API_KEY,
model: process.env.OPENAI_MODEL_NAME ?? 'gpt-4.1',
proxyEndpoint: process.env.OPENAI_API_PROXY_ENDPOINT,

```

### Search Services (Inkeep)

`INKEEP_API_KEY` enables optional search functionality, injected via Vite at [`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts) (line 55).

## Testing and CI/CD Variables

### Integration Test Mode

`INTEGRATION_TEST` enables test-specific behaviors in the CLI toolkit, checked in [`packages/toolkit/core-kit/src/utils/integration-test.ts`](https://github.com/logto-io/logto/blob/main/packages/toolkit/core-kit/src/utils/integration-test.ts) (line 3). Related test infrastructure includes:

- `WEBHOOK_HOST_FOR_APP`: Mock webhook server hostname ([`packages/integration-tests/src/tests/api/hook/WebhookMockServer.ts`](https://github.com/logto-io/logto/blob/main/packages/integration-tests/src/tests/api/hook/WebhookMockServer.ts), line 13)
- `MOCK_CONNECTOR_MESSAGE_DIR`: Storage path for mock connector messages ([`packages/integration-tests/src/helpers/index.ts`](https://github.com/logto-io/logto/blob/main/packages/integration-tests/src/helpers/index.ts), line 53)

### Schema Alteration Flags

Database migration scripts check `CI` (line 6 in alteration scripts like [`1.18.0-add-agree-to-terms-policy.ts`](https://github.com/logto-io/logto/blob/main/1.18.0-add-agree-to-terms-policy.ts)) and `ALTERATION_TEST` (line 8 in [`1.9.0-keep-existing-password-policy.ts`](https://github.com/logto-io/logto/blob/main/1.9.0-keep-existing-password-policy.ts)) to determine execution context.

## Practical Configuration Examples

### Minimal Local Development Environment

Create a `.env` file in your project root:

```dotenv

# Required: Core database connection

DB_URL=postgres://postgres:p0stgr3s@localhost:5432/logto

# API endpoints used by SDKs and tests

ENDPOINT=https://logto.test
ADMIN_ENDPOINT=https://logto.test/admin

# Feature flags

DEV_FEATURES_ENABLED=true
INTEGRATION_TEST=false

# Optional: TLS certificates for HTTPS

HTTPS_CERT_PATH=./certs/server.crt
HTTPS_KEY_PATH=./certs/server.key

# Optional: Analytics configuration

POSTHOG_PUBLIC_KEY=phc_your_key_here
POSTHOG_PUBLIC_HOST=app.posthog.com

# Optional: OpenAI for translation features

OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL_NAME=gpt-4.1

```

### Accessing Variables in Node.js Code

```typescript
import { ConfigKey } from '@logto/shared';
import assert from 'assert';

// Example pattern from packages/cli/src/index.ts#L40
const databaseUrl = process.env[ConfigKey.DatabaseUrl];
assert(databaseUrl, 'DB_URL must be set');

```

### Frontend Injection Pattern

Vite configurations inject variables as `import.meta.env`:

```typescript
// packages/console/vite.config.ts#L47-L52
define: {
  'import.meta.env': {
    NODE_ENV: JSON.stringify(process.env.NODE_ENV),
    DEV_FEATURES_ENABLED: JSON.stringify(process.env.DEV_FEATURES_ENABLED),
    IS_CLOUD: JSON.stringify(process.env.IS_CLOUD),
  },
},

```

## Key Source Files Reference

- **[`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts)**: Central registry for core variables (DB_URL, TLS paths, PostHog, feature flags)
- **[`packages/core/jest.setup.js`](https://github.com/logto-io/logto/blob/main/packages/core/jest.setup.js)**: Default environment setup for core test suites
- **[`packages/cli/src/commands/database/seed/oidc-config.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/commands/database/seed/oidc-config.ts)**: OIDC private key processing during initialization
- **[`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts)**: Frontend build-time variable injection
- **[`packages/app-insights/src/node.ts`](https://github.com/logto-io/logto/blob/main/packages/app-insights/src/node.ts)**: Conditional Azure telemetry initialization
- **[`packages/translate/src/openai.ts`](https://github.com/logto-io/logto/blob/main/packages/translate/src/openai.ts)**: Third-party AI service configuration

## Summary

- **Database connectivity** requires `DB_URL` defined in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts) (line 167)
- **OIDC security** relies on `OIDC_PRIVATE_KEYS` or `OIDC_PRIVATE_KEY_PATHS` during database seeding
- **Frontend builds** receive variables via Vite injection in [`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts) and [`packages/experience/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/experience/vite.config.ts)
- **Feature flags** like `DEV_FEATURES_ENABLED` and `IS_CLOUD` control experimental and cloud-specific functionality
- **Testing modes** use `INTEGRATION_TEST`, `CI`, and `ALTERATION_TEST` to modify behavior in test harnesses and migration scripts

## Frequently Asked Questions

### What is the required minimum set of Logto environment variables to start the server?

You must define `DB_URL` for the PostgreSQL connection. The core server asserts this variable at startup via `assertEnv('DB_URL')` in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts). For HTTPS deployments, also provide `HTTPS_CERT_PATH` and `HTTPS_KEY_PATH`.

### How do I configure Logto environment variables for HTTPS in production?

Set `HTTPS_CERT_PATH` and `HTTPS_KEY_PATH` to the absolute paths of your TLS certificate and private key files. The core server reads these in [`packages/shared/src/node/env/GlobalValues.ts`](https://github.com/logto-io/logto/blob/main/packages/shared/src/node/env/GlobalValues.ts) (lines 71-72) to enable TLS termination.

### Where are frontend-specific variables like DEV_FEATURES_ENABLED processed?

These are processed during the Vite build phase. [`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts) (lines 47-50) injects `DEV_FEATURES_ENABLED`, `NODE_ENV`, and `IS_CLOUD` into the Console SPA, while [`packages/experience/src/constants/env.ts`](https://github.com/logto-io/logto/blob/main/packages/experience/src/constants/env.ts) (line 4) checks the same flags for the Experience app.

### Can I rotate OIDC private keys without downtime using environment variables?

Yes. Use `PRIVATE_KEY_ROTATION_GRACE_PERIOD` defined in [`packages/cli/src/commands/database/config.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/commands/database/config.ts) (line 209) to specify a grace period where both old and new keys remain valid. Provide new keys via `OIDC_PRIVATE_KEYS` or `OIDC_PRIVATE_KEY_PATHS` during the rotation window.