> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data apps

> Configure a self-hosted Lightdash instance to run data apps

<Info>
  Data apps are an **enterprise** feature. You'll need a valid `LIGHTDASH_LICENSE_KEY` set on your instance before any of the configuration below takes effect.
</Info>

[Data apps](/data-apps) are AI-generated React code, built inside an isolated sandbox and stored in an S3-compatible bucket. To enable the feature on a self-hosted instance you need a sandbox provider, a model provider, and a bucket Lightdash can write to. Claude is the default coding agent, and you can run data apps with OpenAI Codex instead.

Sandbox providers are configured separately and cover several runtimes — E2B, AWS Lambda MicroVMs, Azure Container Apps, and Google Cloud Run. See [sandboxes](/self-host/customize-deployment/sandboxes) for the full provider setup; this page covers everything else data apps need.

## Prerequisites

* **Enterprise license** - `LIGHTDASH_LICENSE_KEY` must be set on your instance.
* **S3-compatible storage** - a bucket Lightdash can write to for app source and built artifacts. If your instance isn't already using S3, [set that up first](/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage).
* **A configured sandbox provider** - see [sandboxes](/self-host/customize-deployment/sandboxes).
* **A coding-agent provider** - Anthropic, OpenAI, or an [AWS Bedrock](https://aws.amazon.com/bedrock/) account with access to the model used by your selected agent.

## Configuration

Add the following environment variables to your Lightdash deployment:

| Variable               | Example          | Purpose                                                                                                                                      |
| ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPS_RUNTIME_ENABLED` | `true`           | Main switch for the feature.                                                                                                                 |
| `APPS_CODING_AGENT`    | `claude`         | Coding agent used to generate apps. Supports `claude` (default) or `codex`.                                                                  |
| `APPS_S3_BUCKET`       | `lightdash-apps` | Bucket Lightdash will write app source and built artifacts to. Falls back to `S3_BUCKET` if unset - set this if you want a dedicated bucket. |

Choose one of the coding-agent and provider combinations below.

### Claude through Anthropic (default)

Leave `APPS_CODING_AGENT` unset or set it to `claude`, then provide an Anthropic API key.

| Variable            | Example                    | Purpose                                                                                                                   |
| ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `APPS_CODING_AGENT` | `claude`                   | Optional. Claude is used when this variable is unset.                                                                     |
| `ANTHROPIC_API_KEY` | `<your-anthropic-api-key>` | Your [Anthropic](https://console.anthropic.com/) API key. Used for Data apps when `AI_DEFAULT_PROVIDER` is not `bedrock`. |

Users can choose Sonnet, Opus, or Haiku for each generation. Sonnet is the default.

### Codex through OpenAI

Set `APPS_CODING_AGENT=codex` and provide an OpenAI API key. Codex uses OpenAI directly whenever `AI_DEFAULT_PROVIDER` is not `bedrock`. You do not need an Anthropic API key for Data app generation in this mode.

| Variable            | Example                     | Purpose                                                                                                                      |
| ------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `APPS_CODING_AGENT` | `codex`                     | Runs Data app generation with OpenAI Codex.                                                                                  |
| `OPENAI_API_KEY`    | `<your-openai-api-key>`     | Your [OpenAI API key](https://platform.openai.com/api-keys).                                                                 |
| `OPENAI_BASE_URL`   | `https://api.openai.com/v1` | Optional. Override this for an OpenAI-compatible gateway that supports the Responses API and the configured Codex model IDs. |

Users can choose GPT-5.6 Sol, Terra, or Luna for each generation. Terra is the default.

### Claude or Codex through AWS Bedrock

Set `AI_DEFAULT_PROVIDER=bedrock` to route the selected coding agent through AWS Bedrock. Set `APPS_CODING_AGENT` to `claude` or `codex`, then use a region where the corresponding models are available to your AWS account.

| Variable                    | Example                   | Purpose                                                                                         |
| --------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------- |
| `APPS_CODING_AGENT`         | `claude`                  | Selects `claude` or `codex`. Defaults to `claude`.                                              |
| `AI_DEFAULT_PROVIDER`       | `bedrock`                 | Switches both AI Analyst and Data apps to Bedrock.                                              |
| `BEDROCK_REGION`            | `us-east-2`               | **(Required)** AWS region where the selected model is available.                                |
| `BEDROCK_API_KEY`           | `<your-bedrock-api-key>`  | Bedrock API key (bearer token). Simplest option - use this *or* the IAM keys below, not both.   |
| `BEDROCK_ACCESS_KEY_ID`     | `<aws-access-key-id>`     | AWS access key ID. Use with `BEDROCK_SECRET_ACCESS_KEY` as an alternative to `BEDROCK_API_KEY`. |
| `BEDROCK_SECRET_ACCESS_KEY` | `<aws-secret-access-key>` | AWS secret access key paired with `BEDROCK_ACCESS_KEY_ID`.                                      |
| `BEDROCK_SESSION_TOKEN`     | `<aws-session-token>`     | Optional. AWS session token for temporary IAM credentials.                                      |

For Claude, enable the Claude models you want to use in the selected region. For Codex, enable the corresponding OpenAI model IDs, such as `openai.gpt-5.6-terra`, through the Amazon Bedrock Mantle path. See [OpenAI's Amazon Bedrock guide](https://learn.chatgpt.com/docs/amazon-bedrock) for supported models and authentication requirements.

The Bedrock credentials are the same ones used by AI Analyst - see [AWS Bedrock configuration](/self-host/customize-deployment/environment-variables#aws-bedrock-configuration) for the full reference. The sandbox firewall automatically allows only the provider endpoints required for the selected agent and region.

<Warning>
  `AI_DEFAULT_PROVIDER` is an instance-wide setting. Setting it to `bedrock` also routes AI Analyst through Bedrock. `APPS_CODING_AGENT` changes only the coding agent used by Data apps.
</Warning>

Restart the backend. The "Data apps" entry will appear in the **New** menu for users with the appropriate permission scope.

### Optional configuration

| Variable | Default | Purpose |
| -------- | ------- | ------- |

## Costs

Self-hosting data apps means you pay your sandbox provider and your selected model provider directly:

* **Your sandbox provider** bills for sandbox runtime. A typical build runs for 1–15 minutes; sandboxes are paused between iterations and resumed on follow-up prompts.
* **Anthropic, OpenAI, or AWS Bedrock** bills per token. Each generation sends the project's dbt catalog and the user's prompt to the selected coding agent, plus any attached charts, dashboards, or images.

Both your sandbox provider and your model provider expose usage dashboards. We recommend setting spend limits on both before rolling the feature out to your users.

## Permissions

Data apps follow the same space-based permission model as charts and dashboards. The relevant scopes (`view:DataApp`, `create:DataApp`, `manage:DataApp`) are bundled into the default system roles - but on enterprise instances using custom roles, you'll need to grant them explicitly. See [Custom roles](/workspace-admin/custom-roles) for details.

## Troubleshooting

**The "Data apps" entry doesn't appear in the New menu.**
Check that `APPS_RUNTIME_ENABLED=true`, `LIGHTDASH_LICENSE_KEY` is set, and the signed-in user has the `create:DataApp` scope.

**Builds fail immediately with a sandbox creation error.**
Check your sandbox provider's credentials and template configuration — see [sandboxes](/self-host/customize-deployment/sandboxes).

**Builds fail mid-generation with an Anthropic error.**
Check your Anthropic account usage limits and confirm `ANTHROPIC_API_KEY` is valid. Long-running generations can hit rate limits on lower-tier Anthropic plans.

**Codex builds fail with an OpenAI authentication or model error.**
Confirm `APPS_CODING_AGENT=codex`, `OPENAI_API_KEY` is valid, and your OpenAI project can use the selected GPT-5.6 model. If you set `OPENAI_BASE_URL`, the gateway must support the Responses API and the model IDs shown in the Data app model picker.

**Builds fail mid-generation with a Bedrock error.**
Confirm `BEDROCK_REGION` is set to a region where the selected agent's model is available, and that either `BEDROCK_API_KEY` or the `BEDROCK_ACCESS_KEY_ID` / `BEDROCK_SECRET_ACCESS_KEY` pair is valid. If you use IAM credentials, the principal must have permission to invoke the selected model. Codex requires access to the Bedrock Mantle path and an exact OpenAI Bedrock model ID such as `openai.gpt-5.6-terra`.