AI agents

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

Enterprise AI Analyst and AI agents need a valid LIGHTDASH_LICENSE_KEY set on your instance before any of the configuration below takes effect. See enterprise features for applying the key.

AI Analyst powers natural-language querying, AI-generated charts, and AI agents that answer questions in-app and in Slack. To enable it on a self-hosted instance you need a model provider and the AI Analyst feature flag. Every AI feature that runs on top — Data apps, AI writeback, the managed agent, MCP, and multi-agent Slack channels — assumes AI Analyst is enabled first.

Prerequisites

• Enterprise license — LIGHTDASH_LICENSE_KEY must be set on your instance.
• A model provider — OpenAI, Anthropic, Azure AI, OpenRouter, or AWS Bedrock. OpenAI and Anthropic are the most tested.
• Enough context budget on the chosen model — AI Analyst sends the project’s dbt catalog with every request.

Enable AI Analyst

Set the main switch and provide credentials for one provider — the minimal setup uses OpenAI, the default provider:

AI_COPILOT_ENABLED=true
OPENAI_API_KEY=<your-openai-api-key>

AI Analyst starts using the provider as soon as the backend restarts. To use a different provider, set AI_DEFAULT_PROVIDER (openai, anthropic, azure, openrouter, or bedrock) and the matching credentials — see model providers below. Optionally, set ASK_AI_BUTTON_ENABLED=true to add an “Ask AI” entry point in the app UI; without it, users reach agents from /ai-agents.

Model providers

Each provider’s exhaustive variable list lives in the environment variables reference; the notes below cover the choices and gotchas per provider.

OpenAI (default)

Leave AI_DEFAULT_PROVIDER unset or set it to openai, then set OPENAI_API_KEY. gpt-5.2 is the default model; override it with OPENAI_MODEL_NAME. All options: OpenAI configuration.

Behind an OpenAI-compatible LLM gateway (LiteLLM, an internal proxy), also set OPENAI_BASE_URL to the gateway URL and OPENAI_MODEL_NAME to a model your gateway exposes. If the gateway doesn’t support streaming (SSE), set OPENAI_SUPPORTS_STREAMING=false. If it enforces Zero Data Retention, set OPENAI_ZERO_DATA_RETENTION=true.

Anthropic

Set AI_DEFAULT_PROVIDER=anthropic and provide ANTHROPIC_API_KEY. claude-sonnet-4-5 is the default model; override it with ANTHROPIC_MODEL_NAME. All options: Anthropic configuration.

To send Anthropic traffic through a corporate gateway, add ANTHROPIC_BASE_URL. See Corporate LLM gateways for the required URL, authentication, and API paths.

Azure AI

Set AI_DEFAULT_PROVIDER=azure and point Lightdash at your deployment with AZURE_AI_API_KEY, AZURE_AI_ENDPOINT, AZURE_AI_API_VERSION, and AZURE_AI_DEPLOYMENT_NAME. For reasoning-capable deployments (e.g. o3), also set AZURE_AI_DEPLOYMENT_SUPPORTS_REASONING=true. All options: Azure AI configuration.

OpenRouter

Set AI_DEFAULT_PROVIDER=openrouter and provide OPENROUTER_API_KEY; override the default model with OPENROUTER_MODEL_NAME. All options: OpenRouter configuration.

AWS Bedrock

Set AI_DEFAULT_PROVIDER=bedrock and BEDROCK_REGION (required — the AWS region where the target model is available), then authenticate with either BEDROCK_API_KEY or a BEDROCK_ACCESS_KEY_ID/BEDROCK_SECRET_ACCESS_KEY IAM pair — not both. Enable the corresponding models in the selected region before restarting Lightdash. All options: AWS Bedrock configuration.

To send Bedrock traffic through a corporate gateway, add BEDROCK_BASE_URL. The gateway must support the Bedrock APIs used by every enabled Lightdash consumer. See Corporate LLM gateways.

AI_DEFAULT_PROVIDER is instance-wide. Setting it to bedrock also routes the selected Data apps coding agent through Bedrock. APPS_CODING_AGENT chooses Claude or Codex; it does not change the provider.

Corporate LLM gateways

Lightdash can route AI Analyst and Data app model traffic through an HTTP(S) corporate gateway. Use the base URL for the protocol your gateway exposes:

• OPENAI_BASE_URL for an OpenAI-compatible gateway.
• ANTHROPIC_BASE_URL for an Anthropic Messages gateway.
• BEDROCK_BASE_URL for a Bedrock-compatible gateway.

The gateway URL must include a scheme and must not contain credentials, query parameters, or a fragment. The Lightdash backend and any Data app sandbox must be able to resolve and reach the gateway hostname.

Anthropic-compatible gateway

Configure ANTHROPIC_BASE_URL before the API’s /v1 segment. Lightdash accepts a trailing /v1 and removes it, but using the unversioned base avoids ambiguity:

AI_COPILOT_ENABLED=true
AI_DEFAULT_PROVIDER=anthropic
ANTHROPIC_API_KEY=<gateway-bearer-token>
ANTHROPIC_BASE_URL=https://llm-gateway.example.com/anthropic

When ANTHROPIC_BASE_URL is set, Lightdash sends ANTHROPIC_API_KEY as an Authorization: Bearer token. Without a gateway, direct Anthropic requests continue to use the standard x-api-key header.

Lightdash queries /v1/models to determine which models the credential can access. If the gateway does not expose the Models API, set ANTHROPIC_AVAILABLE_MODELS to the exact comma-separated model names the gateway accepts.

An organization-level BYO Anthropic key cannot be combined with an instance-wide ANTHROPIC_BASE_URL. Remove the organization key to use the gateway, or remove the gateway URL to route that organization through its own Anthropic account.

Bedrock-compatible gateway

Configure the gateway together with the existing Bedrock provider settings:

AI_COPILOT_ENABLED=true
AI_DEFAULT_PROVIDER=bedrock
BEDROCK_REGION=us-east-1
BEDROCK_API_KEY=<gateway-bearer-token>
BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock

The backend Bedrock provider still requires one supported credential mode: BEDROCK_API_KEY, static AWS credentials, or BEDROCK_USE_DEFAULT_CREDENTIALS=true. A custom Bedrock gateway used by Codex requires BEDROCK_API_KEY; Codex cannot combine an overridden endpoint with IAM/SigV4 credentials.

For Claude Data apps, set CLAUDE_CODE_SKIP_BEDROCK_AUTH=true only when the gateway accepts Claude Code requests without AWS authentication. This setting suppresses credentials inside Claude Code; it does not remove the backend provider’s credential requirement.

Required gateway APIs

One base URL can serve multiple consumers only if the gateway implements every wire protocol those consumers use:

Consumer	Required path relative to the configured base
AI Analyst through Anthropic	Anthropic Messages: /v1/messages
Anthropic model discovery	Anthropic Models: /v1/models
AI Analyst through Bedrock	Bedrock Converse: /model/{model-id}/converse or /model/{model-id}/converse-stream
Bedrock verified-answer embeddings	Bedrock Invoke: /model/{model-id}/invoke
Claude Data apps through Anthropic	Anthropic Messages: /v1/messages
Claude Data apps through Bedrock	Bedrock Invoke: /model/{model-id}/invoke-with-response-stream
Codex Data apps through a Bedrock gateway	OpenAI Responses: /responses

A gateway that supports only Bedrock Converse, for example, can serve AI Analyst chat but cannot serve Claude Data app generation. For the coding-agent configuration and model naming rules, see Data apps.

These gateway settings do not reroute AI writeback, the onboarding agent, or the managed agent. When the managed agent is enabled alongside ANTHROPIC_BASE_URL, configure MANAGED_AGENT_ANTHROPIC_API_KEY separately for its direct Anthropic connection.

Validate before rollout

1. Confirm the Lightdash backend can resolve and connect to the gateway hostname.
2. Open AI Analyst and send a short prompt with the configured model. If model discovery fails, verify /v1/models or set ANTHROPIC_AVAILABLE_MODELS.
3. If Data apps are enabled, generate a small app with each coding agent you plan to support. This verifies the sandbox’s separate network path and API wire.
4. Check gateway access logs for the expected paths in the table above. Redact authorization headers and tokens from logs.
5. Restrict direct provider egress only after both backend and sandbox traffic succeed through the gateway.

Verified answers

Verified answers use vector embeddings to match new questions to previously validated ones. Enable embeddings with AI_EMBEDDING_ENABLED=true and pick an embedding provider with AI_DEFAULT_EMBEDDING_PROVIDER (openai, bedrock, or azure). The embedding provider can differ from the chat provider — see verified answers for how they’re used at query time.

Managed agent

The managed agent runs scheduled AI agent tasks on a cron. Provide MANAGED_AGENT_ANTHROPIC_API_KEY and, optionally, a list of allowed MANAGED_AGENT_SKILL_IDS and a custom MANAGED_AGENT_SCHEDULE. Without ANTHROPIC_BASE_URL, the managed agent can fall back to ANTHROPIC_API_KEY. When a gateway is configured, the dedicated key is required because managed-agent beta APIs continue to use Anthropic directly. See autopilot for how the managed agent is used in-product.

Costs

Self-hosting AI Analyst means you pay the selected model provider directly. Every user question sends the project’s dbt catalog plus conversation history to the provider, so long conversations against large projects use noticeably more tokens than one-shot prompts. Provider dashboards expose usage — set spend limits before rolling out.

Permissions

AI Analyst follows the standard project role model: any user with query access to a project can use AI Analyst there. Restrict access at the project level via roles and groups. To limit AI Analyst to specific projects across the instance, set AI_COPILOT_ALLOWED_PROJECT_UUID to a comma-separated list of project UUIDs.

Troubleshooting

The “Ask AI” button doesn’t appear. Confirm AI_COPILOT_ENABLED=true, LIGHTDASH_LICENSE_KEY is set, and ASK_AI_BUTTON_ENABLED=true if you want the top-bar entry point. Users without query access to any project also won’t see it.

AI Analyst returns provider authentication errors. Check the API key for the selected AI_DEFAULT_PROVIDER. For Azure, verify AZURE_AI_ENDPOINT, AZURE_AI_API_VERSION, and AZURE_AI_DEPLOYMENT_NAME all match a deployment your key can call. For Bedrock, confirm the region has the target model enabled for your account.

Multi-step conversations fail against an OpenAI-compatible gateway. If the gateway enforces Zero Data Retention, set OPENAI_ZERO_DATA_RETENTION=true. If it doesn’t support SSE, set OPENAI_SUPPORTS_STREAMING=false.

Verified answers never match. Confirm AI_EMBEDDING_ENABLED=true and that the embedding provider credentials are set. Tune AI_VERIFIED_ANSWER_SIMILARITY_THRESHOLD if legitimate matches fall below the default 0.6 similarity cutoff.