Skip to main content
Apply an Enterprise license key and configure licensed features on your self-hosted Lightdash instance. This section covers deployment setup; each feature links to its product documentation for usage and permissions. For Lightdash Cloud availability, see the feature’s product documentation and Lightdash plans.

​
Get a license key

  1. Contact the Lightdash team to request a self-hosted Enterprise license.
  2. Obtain your license key from the Lightdash team.

​
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

Lightdash validates the license before loading Enterprise services at startup. If your deployment restricts outbound traffic, review Enterprise license validation and the egress matrix before restarting. Feature-specific setup pages describe additional connections to model providers, storage, and other services.

​
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

Configure a model provider and enable the agent runtime with the self-hosted AI agents setup. For creating and using agents, see AI agents.

​
Data apps

Configure the sandbox runtime, model provider, and storage with the self-hosted data apps setup. That page also covers the runtime needed for Chart Studio. For building and managing apps, see Data apps.

​
Chart library

Enable the registry and configure a private mirror if needed with the chart library setup. For installing chart types, see Chart library.

​
AI writeback

Configure the sandbox and model credentials with the AI writeback setup. For repository connections and requesting changes, see AI writeback.

​
MCP

Enable the server and configure network access with the self-hosted MCP setup. For client connections and authentication, see Lightdash MCP.

​
Multi-agent Slack channels

Configure AI agents and the self-hosted Slack integration. Then follow Set up a multi-agent Slack channel and Enable the AI Router for organization-level setup.

​
Embedding

To enable embedding on your instance, add embedding to LIGHTDASH_ENABLE_FEATURE_FLAGS and list the origins allowed to iframe your instance:
If LIGHTDASH_ENABLE_FEATURE_FLAGS already lists flags, append embedding to the comma-separated list. See feature flags. Replace the example domains with your own origins, including the protocol and no trailing slash. The instance needs a valid license. Restart the backend, then follow Set up embedding to configure embed secrets and authentication. See the embedding variables reference for optional settings.

​
Pre-aggregates

Configure storage and query execution with the self-hosted pre-aggregates setup. For model definitions and query behavior, see Pre-aggregates.

​
Custom roles

To enable custom roles on your instance, add custom-roles to LIGHTDASH_ENABLE_FEATURE_FLAGS:
If LIGHTDASH_ENABLE_FEATURE_FLAGS already lists flags, append custom-roles to the comma-separated list. See feature flags. Restart the backend, then follow Custom roles to create and assign roles. The instance needs both a valid license and this flag.

​
Live data sources

To enable live data sources on your instance, add api-query-sources to LIGHTDASH_ENABLE_FEATURE_FLAGS:
If LIGHTDASH_ENABLE_FEATURE_FLAGS already lists flags, append api-query-sources to the comma-separated list. See feature flags. To let people sign in to Google Analytics 4, Search Console, Google Ads and YouTube Analytics, set AUTH_GOOGLE_OAUTH2_CLIENT_ID and AUTH_GOOGLE_OAUTH2_CLIENT_SECRET to the Google OAuth client used for Google sign-in, and enable the Google Analytics Data API, Search Console API, Google Ads API, YouTube Analytics API and YouTube Data API in its Google Cloud project. For Google Ads, also add the https://www.googleapis.com/auth/adwords scope to the client and apply for Google Ads API access for the project. To let people sign in to PostHog, set POSTHOG_OAUTH_CLIENT_ID and POSTHOG_OAUTH_CLIENT_SECRET. Without them, people connect PostHog with a personal API key. To let people connect LinkedIn Ads, create an app in the LinkedIn Developer Portal with access to the Advertising API, add {SITE_URL}/api/v1/ee/linkedin/oauth/callback as a redirect URL, and set LINKEDIN_ADS_OAUTH_CLIENT_ID and LINKEDIN_ADS_OAUTH_CLIENT_SECRET. Without them, LinkedIn Ads shows a Request button. Restart the backend, then follow Connect a live data source.

​
Service accounts

A valid Enterprise license enables service accounts on your instance; no separate environment variable is required. For account creation, token rotation, and permissions, see Service accounts.

​
SCIM

To enable SCIM provisioning on your instance, add scim-token-management to LIGHTDASH_ENABLE_FEATURE_FLAGS:
If LIGHTDASH_ENABLE_FEATURE_FLAGS already lists flags, append scim-token-management to the comma-separated list. See feature flags. The instance needs a valid license. When SCIM runs alongside OIDC SSO, also set AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true so sign-ins can link to SCIM-provisioned users. Restart the backend, then follow SCIM integration for identity-provider setup.

​
Enterprise SSO providers

For provider-specific license requirements and environment settings, follow Configure SSO for self-hosted Lightdash.

​
Usage analytics

Configure collection, object storage, and scheduled refreshes with the self-hosted usage analytics setup. For using the resulting project, see Usage analytics project.

​
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 feature’s required settings and connected services are configured using its setup page.
  4. Check the license validation network requirements.
  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.

Self-host agents

Configure model providers, gateways, and agent services on your Lightdash instance

Self-host the MCP server

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

Self-host data apps

Configure a self-hosted Lightdash instance to run data apps

Self-host pre-aggregates

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

Self-hosted usage analytics

Configure storage, processing, and monitoring for self-hosted usage analytics