From 15c4b9fb13392bee8cae7b9aaa67273cdb44c526 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 4 Jun 2026 15:49:49 +0000 Subject: [PATCH 1/3] docs: add AI writeback self-hosting guide under Agentic development --- docs.json | 3 +- .../developer/ai-writeback-self-hosting.mdx | 72 +++++++++++++++++++ 2 files changed, 74 insertions(+), 1 deletion(-) create mode 100644 guides/developer/ai-writeback-self-hosting.mdx diff --git a/docs.json b/docs.json index b574453d..daf48489 100644 --- a/docs.json +++ b/docs.json @@ -166,7 +166,8 @@ "icon": "code", "pages": [ "guides/developer/agent-skills", - "guides/developer/editing-dashboards-with-agents" + "guides/developer/editing-dashboards-with-agents", + "guides/developer/ai-writeback-self-hosting" ] } ] diff --git a/guides/developer/ai-writeback-self-hosting.mdx b/guides/developer/ai-writeback-self-hosting.mdx new file mode 100644 index 00000000..1ca56f5a --- /dev/null +++ b/guides/developer/ai-writeback-self-hosting.mdx @@ -0,0 +1,72 @@ +--- +title: "AI writeback self-hosting" +sidebarTitle: "AI writeback self-hosting" +description: "Configure your self-hosted Lightdash instance to run the AI writeback agent." +--- + + + AI writeback is an **enterprise** feature and is currently in **Beta**. You'll need a valid `LIGHTDASH_LICENSE_KEY` set on your instance and the feature flag enabled by Lightdash support before any of the configuration below takes effect. + + +AI writeback lets an AI agent edit the dbt repository that backs a project and open a pull request (GitHub) or merge request (GitLab) with the change. The edits run inside an isolated [E2B](https://e2b.dev/) sandbox where a Claude-driven agent applies the diff, runs `lightdash compile` to validate, and pushes a new branch. To enable the feature on a self-hosted Lightdash instance you need to bring your own E2B and Anthropic API keys, and connect the matching Lightdash git app to the repositories you want writeback against. + +For an overview of what the feature does and how to use it in chat, see [AI writeback](/guides/ai-agents/ai-writeback). + +## Prerequisites + +- **Enterprise license** — `LIGHTDASH_LICENSE_KEY` must be set on your instance. +- **AI writeback feature flag** — contact Lightdash support to enable the flag for your organization. +- **An E2B account** — sign up at [e2b.dev](https://e2b.dev/) and create an API key. E2B is the sandbox provider where the writeback agent edits files and runs `lightdash compile`. +- **An Anthropic API key** — sign up at [console.anthropic.com](https://console.anthropic.com/) and create an API key. Claude is the model that drives the writeback agent. +- **A supported git host** — each project that should support writeback must be connected to a **GitHub** or **GitLab** repository (Bitbucket, Azure DevOps, dbt Cloud, and local dbt projects are not supported), with the matching Lightdash app installed: + - **GitHub** — install the Lightdash GitHub App on the repository. + - **GitLab** — connect the Lightdash GitLab App for your organization (self-hosted GitLab is supported via the project's `host_domain`). + +## Configuration + +Add the following environment variables to your Lightdash deployment: + +| Variable | Example | Purpose | +| --- | --- | --- | +| `APPS_RUNTIME_ENABLED` | `true` | Main switch for the sandbox runtime that powers AI writeback. | +| `E2B_API_KEY` | `` | Your [E2B](https://e2b.dev/) API key. Sandboxes are where the writeback agent edits files and runs `lightdash compile`. | +| `E2B_AI_WRITEBACK_TEMPLATE_NAME` | `lightdash-ai-writeback` | Lightdash's public E2B template for writeback — pulls our prebuilt sandbox image so you don't have to build one yourself. | +| `AI_WRITEBACK_ANTHROPIC_API_KEY` | `` | Dedicated [Anthropic](https://console.anthropic.com/) API key used by the writeback agent. Kept separate from `ANTHROPIC_API_KEY` so writeback and AI Analyst have independent spend caps and fail independently. | + +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 dbt 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. | + +## Costs + +Self-hosting AI writeback means you pay E2B and Anthropic directly: + +- **E2B** bills per sandbox-second. 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 — and using `AI_WRITEBACK_ANTHROPIC_API_KEY` rather than reusing `ANTHROPIC_API_KEY` — so writeback spend can be capped independently of AI Analyst. + +## 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](/references/workspace/roles) permissions on the project the agent is connected to. The git commits themselves are made by the installed Lightdash app, not by the end user: + +- **GitHub** commits are signed by the Lightdash GitHub App. +- **GitLab** commits are pushed over OAuth and are unsigned. + +## Troubleshooting + +**The agent never offers to open a pull request.** +Check that `APPS_RUNTIME_ENABLED=true`, `LIGHTDASH_LICENSE_KEY` is set, the AI writeback feature flag is enabled for the organization, and the project's dbt connection is GitHub or GitLab with the matching Lightdash app installed. + +**Writebacks fail immediately with a sandbox creation error.** +Verify `E2B_API_KEY` is valid and that your E2B account has access to the `lightdash-ai-writeback` template. 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 `AI_WRITEBACK_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. From 1173d4f0be2fb099def79785d354e7bd460830ce Mon Sep 17 00:00:00 2001 From: Charlie Dowler Date: Thu, 4 Jun 2026 17:06:28 +0100 Subject: [PATCH 2/3] docs: prefix AI writeback E2B template with lightdash/ team namespace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Self-hosted operators supply their own E2B API key, so a bare `lightdash-ai-writeback` template name resolves to their own (empty) team and fails sandbox creation. The `lightdash/` prefix is required to pull Lightdash's public template — matching the existing data apps self-hosting guide which uses `lightdash/lightdash-data-app`. Co-Authored-By: Claude Opus 4.8 (1M context) --- guides/developer/ai-writeback-self-hosting.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/developer/ai-writeback-self-hosting.mdx b/guides/developer/ai-writeback-self-hosting.mdx index 1ca56f5a..90706056 100644 --- a/guides/developer/ai-writeback-self-hosting.mdx +++ b/guides/developer/ai-writeback-self-hosting.mdx @@ -30,7 +30,7 @@ Add the following environment variables to your Lightdash deployment: | --- | --- | --- | | `APPS_RUNTIME_ENABLED` | `true` | Main switch for the sandbox runtime that powers AI writeback. | | `E2B_API_KEY` | `` | Your [E2B](https://e2b.dev/) API key. Sandboxes are where the writeback agent edits files and runs `lightdash compile`. | -| `E2B_AI_WRITEBACK_TEMPLATE_NAME` | `lightdash-ai-writeback` | Lightdash's public E2B template for writeback — pulls our prebuilt sandbox image so you don't have to build one yourself. | +| `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. | | `AI_WRITEBACK_ANTHROPIC_API_KEY` | `` | Dedicated [Anthropic](https://console.anthropic.com/) API key used by the writeback agent. Kept separate from `ANTHROPIC_API_KEY` so writeback and AI Analyst have independent spend caps and fail independently. | 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 dbt repo. @@ -63,7 +63,7 @@ AI writeback is gated by the user's project role. Anyone asking the agent to ope Check that `APPS_RUNTIME_ENABLED=true`, `LIGHTDASH_LICENSE_KEY` is set, the AI writeback feature flag is enabled for the organization, and the project's dbt connection is GitHub or GitLab with the matching Lightdash app installed. **Writebacks fail immediately with a sandbox creation error.** -Verify `E2B_API_KEY` is valid and that your E2B account has access to the `lightdash-ai-writeback` template. If you've overridden `E2B_AI_WRITEBACK_TEMPLATE_TAG`, double-check the tag exists. +Verify `E2B_API_KEY` is valid and that `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 `AI_WRITEBACK_ANTHROPIC_API_KEY` is valid. Long-running writebacks can hit rate limits on lower-tier Anthropic plans. From f8cb824705cbd1d2bce6e00f59c6aacb5ec7aa23 Mon Sep 17 00:00:00 2001 From: Charlie Dowler Date: Thu, 4 Jun 2026 17:17:04 +0100 Subject: [PATCH 3/3] docs: drop APPS_RUNTIME_ENABLED from AI writeback self-hosting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit APPS_RUNTIME_ENABLED only gates the data apps feature (it force-enables the enable-data-apps flag and registers the preview routes). The AI writeback path never checks it — writeback is gated solely by the ai-writeback feature flag and reads E2B_API_KEY unconditionally. Listing it as a required "main switch" was inaccurate, so remove it from the config table and troubleshooting. Co-Authored-By: Claude Opus 4.8 (1M context) --- guides/developer/ai-writeback-self-hosting.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guides/developer/ai-writeback-self-hosting.mdx b/guides/developer/ai-writeback-self-hosting.mdx index 90706056..94b717e6 100644 --- a/guides/developer/ai-writeback-self-hosting.mdx +++ b/guides/developer/ai-writeback-self-hosting.mdx @@ -28,7 +28,6 @@ Add the following environment variables to your Lightdash deployment: | Variable | Example | Purpose | | --- | --- | --- | -| `APPS_RUNTIME_ENABLED` | `true` | Main switch for the sandbox runtime that powers AI writeback. | | `E2B_API_KEY` | `` | Your [E2B](https://e2b.dev/) API key. Sandboxes are where the writeback agent edits files and runs `lightdash compile`. | | `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. | | `AI_WRITEBACK_ANTHROPIC_API_KEY` | `` | Dedicated [Anthropic](https://console.anthropic.com/) API key used by the writeback agent. Kept separate from `ANTHROPIC_API_KEY` so writeback and AI Analyst have independent spend caps and fail independently. | @@ -60,7 +59,7 @@ AI writeback is gated by the user's project role. Anyone asking the agent to ope ## Troubleshooting **The agent never offers to open a pull request.** -Check that `APPS_RUNTIME_ENABLED=true`, `LIGHTDASH_LICENSE_KEY` is set, the AI writeback feature flag is enabled for the organization, and the project's dbt connection is GitHub or GitLab with the matching Lightdash app installed. +Check that `LIGHTDASH_LICENSE_KEY` is set, the AI writeback feature flag is enabled for the organization, and the project's dbt connection is GitHub or GitLab with the matching Lightdash app installed. **Writebacks fail immediately with a sandbox creation error.** Verify `E2B_API_KEY` is valid and that `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.