AI writeback

Enable AI writeback on a self-hosted Lightdash instance

Enterprise AI writeback needs a valid LIGHTDASH_LICENSE_KEY set on your instance (enterprise features covers applying the key) before any of the configuration below takes effect.

AI writeback lets an AI agent edit the semantic layer repository that backs a project and open a pull request with the change. The edits run inside an isolated sandbox. Validation depends on the project format; see how AI writeback works. To enable the feature on a self-hosted Lightdash instance you need a configured sandbox provider, an Anthropic API key, and repository access.

For an overview of what the feature does and how to use it in chat, see AI writeback.

Prerequisites

• Enterprise license — LIGHTDASH_LICENSE_KEY must be set on your instance.
• A configured sandbox provider — see sandboxes. The writeback agent edits files there.
• An Anthropic API key — sign up at console.anthropic.com and create an API key. Claude is the model that drives the writeback agent.
• Repository access — configure a supported provider and semantic layer format using the AI writeback prerequisites.

Configuration

Add the following environment variables to your Lightdash deployment:

Variable	Example	Purpose
E2B_AI_WRITEBACK_TEMPLATE_NAME	lightdash/lightdash-ai-writeback	Lightdash’s public E2B template for writeback — pulls our prebuilt sandbox image so you don’t have to build one yourself. The lightdash/ prefix points at our public team template; without it E2B looks in your own team and won’t find the image.
ANTHROPIC_API_KEY	<your-anthropic-api-key>	Your Anthropic API key. Claude is the model that drives the writeback agent.

Restart the backend. Users with AI Analyst access on a project connected to a supported git host will see the agent offer to open a pull request when they ask for a change that belongs in the semantic layer repo.

Optional configuration

Variable	Default	Purpose
E2B_AI_WRITEBACK_TEMPLATE_TAG	Running Lightdash version (e.g. 0.2917.1)	Pins the writeback sandbox image to a specific tag of the E2B template. Each Lightdash release publishes a matching tag so the backend and sandbox stay in sync. Override this to roll back to a previous build or set it to an empty string to use the template’s default tag. Most operators don’t need to touch this.

Supported dbt versions

This section applies to dbt projects. Native Lightdash YAML uses native validation and needs no dbt installation.

The writeback sandbox runs lightdash compile using the dbt version configured on the project, so validation behaves the same way it would locally. The sandbox 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 exact version.
• Projects set to latest compile against the newest available version (currently 1.12).
• Projects pinned to a version below 1.8 (which is end-of-life upstream) are clamped up to 1.8 inside the sandbox.

You don’t need to configure anything — the version is selected automatically from the project’s dbt connection settings.

Costs

Self-hosting AI writeback means you pay your sandbox provider and Anthropic directly:

• Your sandbox provider bills for sandbox runtime. A typical writeback runs for 1–5 minutes while the agent inspects files, edits them, and runs lightdash compile.
• Anthropic bills per token. Each writeback sends the project’s dbt catalog and the self-contained instruction generated from the user’s request to Claude, plus any files the agent reads while making the change.

Both providers expose usage dashboards. We recommend setting spend limits on both.

Permissions

AI writeback is gated by the user’s project role. Anyone asking the agent to open a pull request needs at least project Developer permissions on the project the agent is connected to. Git authentication depends on the provider:

• GitHub commits are signed by the Lightdash GitHub App.
• GitLab commits are pushed over OAuth and are unsigned.
• Bitbucket Cloud uses the project API token owner’s identity.

Troubleshooting

The agent never offers to open a pull request. Check that LIGHTDASH_LICENSE_KEY is set and the project meets the repository and permission prerequisites.

Writebacks fail immediately with a sandbox creation error. Check your sandbox provider’s credentials, and verify E2B_AI_WRITEBACK_TEMPLATE_NAME is set to lightdash/lightdash-ai-writeback (the lightdash/ prefix is required to pull our public template — a bare name resolves to your own team). If you’ve overridden E2B_AI_WRITEBACK_TEMPLATE_TAG, double-check the tag exists.

Writebacks fail mid-run with an Anthropic error. Check your Anthropic account usage limits and confirm ANTHROPIC_API_KEY is valid. Long-running writebacks can hit rate limits on lower-tier Anthropic plans.

The agent surfaces a GitHub App is not installed or GitLab App is not installed error. Install the Lightdash GitHub App on the repository (from the project’s dbt connection settings) or connect the Lightdash GitLab App for your organization, then ask the agent to try again.