Skip to main content
Enable AI agents on a self-hosted Lightdash instance, then configure your model provider, network access, and optional agent services. For creating agents, connecting Slack, and managing organization-level models, follow Set up agents. After configuring a model provider, enable the extensions your deployment needs: post-processing, verified answers, AI writeback, Autopilot, or agent identity.

​
Prerequisites

  • Apply a valid Enterprise license key.
  • Configure a model provider: OpenAI, Anthropic, Google Gemini, Google Vertex AI, Azure AI, OpenRouter, or AWS Bedrock.
  • Allow the backend and any scheduler or worker running agent jobs to reach the provider or your corporate gateway.

​
Enable AI agents

Set the main switch and provide credentials for one provider — the minimal setup uses OpenAI, the default provider:
Apply the same provider configuration to the backend and any scheduler or worker running agent jobs, then restart those processes. To use a different provider, set AI_DEFAULT_PROVIDER and its matching credentials. Optionally, set ASK_AI_BUTTON_ENABLED=true to show the Ask AI entry point; users can also reach agents at /ai-agents.

​
Model providers

Find provider credentials, supported models, and defaults in the environment variables reference. Set AI_DEFAULT_PROVIDER to openai, anthropic, google, vertex, azure, openrouter, or bedrock, then follow that provider’s configuration:

​
OpenAI (default)

Follow 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. If it only implements the Chat Completions API (/chat/completions) and returns 404 for /responses, set OPENAI_USE_CHAT_COMPLETIONS=true.

​
Anthropic

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

​
Google Gemini

Follow Google Gemini configuration. Use GEMINI_BASE_URL for a compatible gateway.

​
Google Vertex AI

Follow Google Vertex AI configuration. If you use Application Default Credentials, make them available to both the backend and scheduler.

​
Azure AI

Follow Azure AI configuration. If your gateway only implements the Chat Completions API, set AZURE_AI_USE_CHAT_COMPLETIONS=true. Set AZURE_AI_REASONING_EFFORT to a value your deployment accepts if it rejects the default reasoning setting.

​
OpenRouter

Follow OpenRouter configuration.

​
AWS Bedrock

Follow AWS Bedrock configuration, and enable the selected models in your AWS region. The agent chat provider supports Claude models; Data apps has separate coding-agent model support. 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 agent, Autopilot, 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. Each caller must be able to resolve and reach its configured gateway hostname.

​
Separate gateway routes for Data apps

If the backend and Data app sandboxes need different URLs to reach your LLM gateway, configure a sandbox-only base URL:
The Data app coding agent uses the DATA_APPS_ override when set and falls back to the shared provider URL when it is unset or empty. The same option is available for Bedrock and OpenAI; see the environment variable reference for all three variables. Anthropic URLs use the base before /v1; OpenAI URLs retain their API path, commonly /v1. These overrides apply to instance-managed credentials only. Organizations using their own AI keys retain their resolved provider endpoints. Backend AI requests, AI writeback, and onboarding keep their existing routing. Provider selection and credentials stay unchanged; the sandbox URL must accept the existing coding agent’s authentication and API protocol. Provider *_CUSTOM_HEADERS are not forwarded to the coding agent. Restart the Lightdash backend and scheduler workers after changing these environment variables. Check sandbox gateway egress, including the requirements for existing sandboxes.

​
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:
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 unless the organization sets its own custom base URL, which replaces the gateway for that organization’s traffic. Otherwise, remove the organization key to use the gateway, or remove the gateway URL to route that organization through its own Anthropic account. The same rule applies to organization Google Gemini keys and GEMINI_BASE_URL.

​
Bedrock-compatible gateway

Configure the gateway together with the existing Bedrock provider settings:
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: A gateway that supports only Bedrock Converse can serve agent chat but cannot serve Claude Data app generation. For coding-agent configuration and model naming rules, see Self-hosted Data apps.
These gateway settings do not reroute AI writeback or the onboarding agent. Autopilot uses the same provider configuration as AI agents. Its scheduler must also be able to reach the gateway.

​
Validate before rollout

  1. Confirm the Lightdash backend and any scheduler running Autopilot can resolve and connect to the gateway hostname.
  2. Open an AI agent 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. If Autopilot is enabled, run it on a disposable project and check its recorded provider, model, and outcome. A successful configuration check does not prove the gateway accepts a model request.
  5. Check gateway access logs for the expected paths in the table above. Redact authorization headers and tokens from logs.
  6. Restrict direct provider egress only after all enabled consumers succeed through the gateway.

​
Post-processing with DuckDB and Python

Agents can post-process query results with DuckDB and Python. On Lightdash Cloud this is managed for you. On a self-hosted instance each step type has its own requirement:

​
1. Configure results storage

DuckDB steps read the result files of the queries they reference straight from object storage, so results storage is required. Set S3_ENDPOINT, S3_BUCKET and S3_REGION, or the RESULTS_S3_* overrides. See external object storage. If the endpoint uses HTTPS, the Lightdash image needs a CA certificate bundle. The official image ships one. On a custom image, install ca-certificates or set SSL_CERT_FILE to a PEM bundle. Without one, DuckDB steps fail with a configuration error. DuckDB shares the pre-aggregate memory budget. To cap it, set PRE_AGGREGATE_DUCKDB_QUERY_MEMORY_LIMIT (for example 2GB).

​
2. Set up the Python sandbox (optional)

Python steps need a sandbox provider that supports Python execution: E2B, Azure Container Apps Sandboxes, or Google Cloud Run. AWS Lambda MicroVMs doesn’t support it. Follow Python execution to build the image and configure the provider. Without a Python sandbox, DuckDB steps still work, but Python steps fail.

​
3. Configure external data (optional)

To let users attach CSVs to a thread, configure the pre-aggregates bucket with PRE_AGGREGATE_RESULTS_S3_*. See pre-aggregate workers.

​
4. Turn it on

Post-processing is gated by the compose-sql-runner feature flag, off by default. Set it on the backend and the scheduler, then restart both:
Agents also need data access that lets them read rows. With the flag on, each agent has a Composer queries setting, on by default, that admins can turn off per agent. For data access rules and execution boundaries, see Post-process results with DuckDB and Python.

​
Verified answers

To enable verified answers on your instance, set AI_EMBEDDING_ENABLED=true and configure an embedding provider with AI_DEFAULT_EMBEDDING_PROVIDER (openai, bedrock, or azure). The embedding provider can differ from the chat provider. See the embedding configuration for credentials and options.

​
AI writeback

Enable AI writeback on your self-hosted instance by configuring a sandbox and Anthropic credentials. For supported repositories, permissions, and using writeback in chat, see AI writeback.

​
Writeback prerequisites

  • Configure a sandbox provider that supports writeback. Google Cloud Run does not support it.
  • Create an Anthropic API key. Writeback uses Claude even if your AI agents use another model provider.
  • Configure repository access using the AI writeback prerequisites.

​
Writeback configuration

Set ANTHROPIC_API_KEY in your Lightdash deployment. For E2B, select Lightdash’s public writeback template:
Keep the lightdash/ prefix: a bare template name resolves to your own E2B team. Other providers use their writeback-specific image configuration; see sandbox providers. Restart the backend, then ask an agent for a repository change to verify the setup.

​
Writeback image version

Leave E2B_AI_WRITEBACK_TEMPLATE_TAG unset to use the sandbox build matching your Lightdash version. Override it only when you need to pin a build; an empty value selects the template’s default tag. See the runtime variables reference for all writeback image settings.

​
Writeback dbt versions

For dbt projects, the writeback sandbox runs lightdash compile using the project’s dbt version. It ships with dbt 1.8, 1.9, 1.10, 1.11, and 1.12 preinstalled:
  • Projects pinned to one of those versions compile against that version.
  • Projects set to latest compile against the highest version in the sandbox.
  • Projects pinned below 1.8 compile against 1.8 in the sandbox.
The version is selected automatically from the project’s dbt connection settings. Native Lightdash YAML uses native validation and needs no dbt installation.

​
Writeback provider usage

Your sandbox provider and Anthropic bill your accounts directly. Monitor usage and configure limits with those providers before rolling out writeback.

​
Writeback troubleshooting

​
Autopilot

Autopilot needs AI agents enabled and a provider configured through the instance model settings or organization AI providers and models. It uses the shared AI provider configuration, with no separate runtime selector or provider credentials. Use a provider’s *_AVAILABLE_MODELS variable to restrict its selectable models. For model selection and organization settings, see AI provider and usage. Enable the Autopilot feature on every API and scheduler process:
Append ai-autopilot if the enable list already contains other flags, and remove it from LIGHTDASH_DISABLE_FEATURE_FLAGS if present. Restart the API and scheduler after changing environment variables. Keep their provider and Autopilot configuration consistent; the scheduler executes scheduled runs and needs access to the selected provider or gateway. After restarting, follow Autopilot setup to enable it for a project. Run it on a disposable project to verify credentials, model access, and gateway routing; enabling it does not make a model request.

​
Schedule and limits

Configure the fallback schedule, run deadline, and model step limit with the Autopilot environment variables. These limits do not set a spending cap; use your provider’s controls to manage cost.

​
Model qualification and cleanup

Autopilot only flags or deletes content on models that are qualified for it. Every other model runs in observe mode. When MANAGED_AGENT_VALIDATED_MODELS is unset, these models are qualified for cleanup: Choose a qualified model in the organization settings or the provider’s model environment variable when you want Autopilot to flag or delete content. A provider’s default model is not necessarily qualified. Azure deployments, Google Gemini, Google Vertex AI, OpenRouter and any model not listed above start in observe mode. To qualify one, set MANAGED_AGENT_VALIDATED_MODELS to a JSON array of exact provider/model pairs with a mode of observe, flag, or cleanup. Setting the variable replaces the built-in list, so include the built-in models you still want; an empty value qualifies no model. Duplicate qualifications use the most restrictive mode; malformed configuration rejects startup. Qualify a model on disposable representative content before increasing its permissions. Use the exact model IDs shown in Autopilot; Bedrock Claude inference-profile region prefixes are also accepted without the prefix. Autopilot uses the more restrictive of the project’s requested cleanup mode and the model’s qualification. A downgrade appears in setup and the run summary. Observe mode does not mean read-only: chart creation and repair still follow the project’s capability toggles. Disable those capabilities as well when evaluating without content changes.

​
Upgrading from the hosted runtime

Lightdash 2.262.0 removed the hosted runtime. From that version Autopilot always runs on your configured AI provider.
  • Nothing to change to keep Autopilot running. Provider credentials come from the shared AI configuration described above. Keep the schedule and timeout settings, and review the step limit and model qualifications.
  • Remove the old settings. MANAGED_AGENT_RUNTIME, MANAGED_AGENT_ANTHROPIC_API_KEY, and MANAGED_AGENT_SKILL_IDS are retired and ignored. Compatibility warnings may appear at startup while these variables remain set.
  • No configuration rollback. Setting MANAGED_AGENT_RUNTIME=anthropic-managed cannot restore the hosted runner. To roll back, redeploy a release before 2.262.0 with the credentials it needs.
On releases 2.255.0 to 2.261.x both runtimes exist and the AI SDK runner is the default. MANAGED_AGENT_RUNTIME selects the runner there and must match on the API and scheduler processes.

​
Agent identity

Enable agent identity on your self-hosted instance with the agent-identity feature flag.
1

Enable the feature flag

Add agent-identity to LIGHTDASH_ENABLE_FEATURE_FLAGS on every backend/API replica and on any scheduler or worker process that executes AI agent jobs:
Append agent-identity if the list already contains other flags, and remove it from LIGHTDASH_DISABLE_FEATURE_FLAGS if present.
2

Restart

Restart the affected processes. Lightdash reads these variables at startup.
After restarting, follow Agent identity for warehouse support, organization rules, and shared account setup. For Snowflake agent sign-in, also review Agent identity on Snowflake. Lightdash checks that the identity that produced a saved result matches the reader. See Who can read a saved result. If this comparison causes a problem on your instance, set AGENT_RESULT_IDENTITY_CHECK_ENABLED=false to turn it off. The access checks stay on. See Agent identity variables. Each agent query writes one structured info log line with the message Agent query before it runs in the warehouse. Set LIGHTDASH_LOG_FORMAT=JSON to keep the fields: queryUuid, projectUuid, warehouseConnectionUuid, userUuid, identity (marked_person, connected_person or ai_service_account), actorKind, principalKind, credentialUuid, identityUuid, principalRef and context. The line does not include the person’s email. See logging.

​
Agent identity audit entries and logs

Lightdash writes agent identity changes and failures to the application log. It does not store them in a table. Collect them from the log output of every backend/API replica and every scheduler or worker process.

​
Audit entries

Admin changes write an entry at the audit log level. The audit level is below info, so set LIGHTDASH_LOG_LEVEL=audit or LIGHTDASH_LOG_LEVEL=debug to write them. With the default level (http in production), Lightdash does not write audit entries. Each entry has the actor who made the change, the action, the resource and the status. resource.metadata.event names the change: source and previousSource are marked_person (The person), agent_sign_in (The person’s agent sign-in) or ai_service_account (A shared agent account). resource.organizationUuid is on every entry, and resource.projectUuid is on shared agent account entries. A generation changes each time the key changes, so compare previousGeneration and generation to see that a key was replaced. If your log indexer maps the actor field as text, set LIGHTDASH_LOG_AUDIT_ACTOR_AS_STRING=true.

​
Log lines

Lightdash also logs these events at the default levels: BigQuery key refusals, Snowflake session check refusals and shared agent account test failures also log the redacted warehouse error. A status or diagnostic check that only reports a refusal logs at debug.

​
What Lightdash does not log

  • Keys, tokens, client secrets and client emails are never in an audit entry or a log line.
  • A logged warehouse error has errorClass, errorCode, errorCategory and a redacted errorMessage. Lightdash removes key blocks, quoted text and SQL from the message, and keeps only plain words and short numbers. errorCategory is a fixed value, for example invalid_grant, token_expired or permission_denied.
  • No SQL or result data is logged in these entries.
  • In access log URLs, Lightdash replaces the values of the OAuth code and state parameters with [REDACTED].

​
Agent identity on Snowflake

Follow Set up the Snowflake agent integration for the in-app steps and Snowflake SQL. Lightdash encrypts the saved client secret with your instance’s LIGHTDASH_SECRET. The setup SQL uses your instance’s redirect URL: <siteHost>/api/v1/oauth/redirect/snowflake-ai, where <siteHost> is the scheme and host of SITE_URL. It uses the host root even when SITE_URL has a path. Check that this address is reachable from the browser completing sign-in.
To test over http://localhost, add OAUTH_ALLOW_NON_TLS_REDIRECT_URI = TRUE to the integration. This is for local development only. Do not set it in production.

​
Costs

For self-hosted AI agents, you pay the model provider directly. Set provider spending limits before rollout, and use warehouse quotas to control query costs. Review agent activity alongside your provider’s usage dashboard. For agent scope and context guidance, see Data access and Effective analytics with agents.

​
Compact filter expressions

Compact filter expressions replace verbose structured filter schemas for AI agent and Model Context Protocol (MCP) query tools with a smaller expression syntax. This reduces the filter-related tool definitions and inputs sent to the model. Total savings vary by model, conversation history, caching, and tool usage; the setting does not reduce the catalog, existing conversation history, or query results. On a self-hosted deployment, enable compact filter expressions on every backend/API replica and on any scheduler or worker process that executes AI agent jobs, then redeploy or recreate those containers:
If LIGHTDASH_ENABLE_FEATURE_FLAGS already contains other flags, append ai-filter-expressions to its comma-separated list. Remove it from LIGHTDASH_DISABLE_FEATURE_FLAGS if present. Lightdash reads both variables at process startup. Users do not need to create new agents or threads: the next response uses compact filter expressions, including in an existing thread. After enabling the feature for MCP, reconnect or refresh each client so it reloads the query tool definitions.

​
Permissions

Configure agent access through agent permissions and project roles. Instance configuration does not replace those controls.

​
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 agents return 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. Every agent request to an OpenAI-compatible gateway returns 404. Lightdash uses the OpenAI Responses API by default. Gateways such as LiteLLM, Kong, or internal proxies often only implement the older Chat Completions API. Set OPENAI_USE_CHAT_COMPLETIONS=true (or AZURE_AI_USE_CHAT_COMPLETIONS=true for the Azure provider) to send /chat/completions requests instead. Extended reasoning summaries aren’t available on Chat Completions: tool calls work, but reasoning models run with reasoning disabled. Verified answers never match. Confirm AI_EMBEDDING_ENABLED=true and that the embedding provider credentials are set. See the similarity threshold setting if legitimate matches are rejected.