Skip to main content
🛠 This page is for engineering teams self-hosting their own Lightdash instance. If you want to learn about enterprise features and pricing, go to lightdash.com/pricing. An enterprise license key unlocks Lightdash Enterprise Edition features on a self-hosted instance. Some features also need environment variables, organization settings, or connected services. This page covers getting and applying the key, then each feature — the ones that need a flag or two are enabled right here, and the larger ones (AI agents, data apps, chart library, AI writeback, MCP, and pre-aggregates) each have a dedicated setup page linked from their section.

​
Get a license key

  1. Contact the enterprise team — schedule a call to discuss your requirements.
  2. Receive your key — the Lightdash team will share the key with you, typically via 1Password.

​
Apply the license key

Set LIGHTDASH_LICENSE_KEY on every Lightdash container: backend, scheduler, and workers.
Restart every container after adding the key.

​
License validation and network requirements

On server start, Lightdash validates the license key by making an outbound HTTPS request to the Keygen license validation API:
  • Endpoint: https://api.keygen.sh
  • Purpose: validates the key provided in LIGHTDASH_LICENSE_KEY
  • When: on every Lightdash server start
Your Lightdash instance must be able to reach https://api.keygen.sh on server start. This is the only external network request required to run Lightdash with enterprise features. If your environment restricts outbound traffic, allow-list this endpoint in your firewall or proxy.Once the license validates, the backend also fetches the organization roadmap from https://roadmap.lightdash.com — allow-list that domain too.
No external code is pulled during validation — the request only checks the key and returns the result. For the exact request payload and how it fits into the broader self-hosted network picture, see Data flows and telemetry — Enterprise license validation.

​
Verify the license

After applying the key and restarting:
  1. Log in to Lightdash.
  2. Click the version number in the page footer to open About Lightdash.
  3. Check the Enterprise license row: Valid means enterprise features are enabled, Not valid means the configured key failed validation, and No license means the server can’t see a key.

​
Features

​
AI agents

AI Analyst and AI agents bring natural-language querying, AI-generated charts, and agents that answer questions in-app and in Slack. Set AI_COPILOT_ENABLED=true and configure a model provider — see AI agents. Every other AI feature below assumes this one is enabled first.

​
Data apps

Data apps are AI-generated React apps, built inside an isolated sandbox and served from an S3-compatible bucket. Set APPS_RUNTIME_ENABLED=true with a sandbox provider, a model provider, and a bucket — see data apps. Chart Studio uses the same runtime and turns on once the sandbox provider is configured, without APPS_RUNTIME_ENABLED.

​
Chart library

The chart library lets project admins install ready-made chart types built by Lightdash. Add chart-type-registry to LIGHTDASH_ENABLE_FEATURE_FLAGS — see chart library for reading it from a private mirror on a restricted network.

​
AI writeback

AI writeback lets an agent edit the dbt repository behind a project and open a pull request with the change. Configure the writeback sandbox and its Anthropic key — see AI writeback.

​
MCP

Lightdash can expose a Model Context Protocol server at /api/v1/mcp for AI assistants to query the semantic layer. Set MCP_ENABLED=true — see MCP for connecting assistants and network requirements.

​
Multi-agent Slack channels

Multi-agent Slack channels let one Slack channel host every AI agent in the organization, with the AI Router picking the best-fit agent per question. Requires AI agents and the Slack integration; no extra environment variable is needed. Designate the channel from the AI Agents organization settings — see setting up a multi-agent Slack channel for the in-app steps.

​
Embedding

Embedding renders Lightdash dashboards, charts, data apps, and AI agents inside your own product, authenticated with a JWT signed by an embed secret. Set:
LIGHTDASH_IFRAME_EMBEDDING_DOMAINS is the comma-separated allow-list of origins (protocol included, no trailing slash) permitted to iframe Lightdash — if an embed URL loads on its own but the iframe stays blank, the host origin is missing from this list. Restart the backend, then generate an embed secret from Project settings → Embed configuration. The embedding variables reference covers the optional settings, including the embed event system.

​
Pre-aggregates

Pre-aggregates materialize aggregated tables to S3 and route matching queries to DuckDB instead of your warehouse. They need NATS, an S3-compatible bucket, and a dedicated worker deployment alongside the flag — see pre-aggregates.

​
Custom roles

Custom roles let organization admins define roles with a chosen set of permission scopes, beyond the built-in Admin, Developer, Editor, and Viewer roles. Set:
Restart the backend. Organization admins can then build and assign roles from Settings → Custom roles (under Organization settings). The Custom roles item appears only when the license key is applied and CUSTOM_ROLES_ENABLED=true, and only to organization admins. Otherwise, opening /generalSettings/customRoles directly redirects to your profile settings.

​
Service accounts

Service accounts are userless, scoped credentials for CLI and API access that outlive their creator. They are available with a valid Enterprise license; no separate environment variable is required. Admins can create and rotate tokens from Organization settings → Service accounts.

​
SCIM

SCIM 2.0 automates user and group provisioning from an identity provider such as Okta, Azure AD, or OneLogin. Set:
When SCIM runs alongside SSO, also set AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true — without it, Lightdash tries to create a new user on SSO sign-in and fails because the email is already taken by the SCIM-provisioned user. Restart the backend, then follow SCIM integration for the provider-side setup.

​
Enterprise SSO providers

SSO providers such as Google Workspace are available on all plans, but Okta, Azure AD, OneLogin, generic OIDC, Snowflake OAuth, and Databricks OAuth require the license key on self-hosted instances — see Configure SSO for self-hosted Lightdash for the full setup. For the exhaustive list of environment variables that require an enterprise license key, search “enterprise” on the environment variables reference.

​
Usage analytics

The usage analytics project provides organization-wide dashboards and Explores over captured usage. It requires the organization-level analytics-project flag and object storage. Follow the self-hosted usage analytics setup to configure collection and scheduled refreshes.

​
Troubleshooting

If enterprise features are unavailable after applying the key:
  1. Confirm LIGHTDASH_LICENSE_KEY is set on every Lightdash container (backend, scheduler, workers). On Kubernetes, check the environment of the running pod, not only the Secret: a Secret that exists but isn’t mounted into the pod leaves the variable unset.
  2. Confirm every container was restarted after adding the key.
  3. Confirm the per-feature environment flag is set (for example, AI_COPILOT_ENABLED=true for AI Analyst).
  4. Confirm the server can reach https://api.keygen.sh.
  5. Check the Lightdash logs for license-related errors.
  6. Contact enterprise support if the issue persists.
Without a valid key, Lightdash starts without its enterprise services, even when the per-feature flag is set. Requests to those features then fail with an error like Unable to initialize service 'serviceAccountService' - no factory or provider. When the key is present but invalid, the backend logs a warning that starts with Enterprise license for <SITE_URL> on startup.

AI agents

Enable AI Analyst and AI agents on a self-hosted Lightdash instance

Data apps

Configure a self-hosted Lightdash instance to run data apps

Chart library

Enable the chart library on a self-hosted Lightdash instance, or point it at a private mirror

AI writeback

Enable AI writeback on a self-hosted Lightdash instance

MCP

Enable the Model Context Protocol server on a self-hosted Lightdash instance

Pre-aggregates

Enable pre-aggregate query routing on a self-hosted Lightdash instance

Usage analytics

Configure storage and collection for a self-hosted usage analytics project