AI writeback
Enable AI writeback on a self-hosted Qyra instance
Enterprise AI writeback needs a valid QYRA_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 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 sandbox where a Claude-driven agent applies the diff, runs qyra compile to validate, and pushes a new branch. To enable the feature on a self-hosted Qyra instance you need a configured sandbox provider, an Anthropic API key, and the matching Qyra git app connected 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.
Prerequisites
- Enterprise license —
QYRA_LICENSE_KEYmust be set on your instance. - A configured sandbox provider — see sandboxes. The writeback agent edits files and runs
qyra compilethere. - An Anthropic API key — sign up at 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 Qyra app installed:
- GitHub — install the Qyra GitHub App on the repository.
- GitLab — connect the Qyra GitLab App for your organization. Writeback works against GitLab.com; self-hosted GitLab domains aren't reachable from the writeback sandbox yet.
Configuration
Add the following environment variables to your Qyra deployment:
| Variable | Example | Purpose |
|---|---|---|
E2B_AI_WRITEBACK_TEMPLATE_NAME | qyra/qyra-ai-writeback | Qyra's public E2B template for writeback — pulls our prebuilt sandbox image so you don't have to build one yourself. The qyra/ 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 dbt repo.
Optional configuration
| Variable | Default | Purpose |
|---|---|---|
E2B_AI_WRITEBACK_TEMPLATE_TAG | Running Qyra version (e.g. 0.2917.1) | Pins the writeback sandbox image to a specific tag of the E2B template. Each Qyra 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
The writeback sandbox runs qyra 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
latestcompile 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
qyra 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. The git commits themselves are made by the installed Qyra app, not by the end user:
- GitHub commits are signed by the Qyra GitHub App.
- GitLab commits are pushed over OAuth and are unsigned.
Troubleshooting
The agent never offers to open a pull request.
Check that QYRA_LICENSE_KEY is set and the project's dbt connection is GitHub or GitLab with the matching Qyra app installed.
Writebacks fail immediately with a sandbox creation error.
Check your sandbox provider's credentials, and verify E2B_AI_WRITEBACK_TEMPLATE_NAME is set to qyra/qyra-ai-writeback (the qyra/ 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 Qyra GitHub App on the repository (from the project's dbt connection settings) or connect the Qyra GitLab App for your organization, then ask the agent to try again.