This is a reference to all environment variables that can be used to configure a Qyra deployment.

Postgres database

These variables configure the Postgres database Qyra uses to store its own application data (not your warehouse).

Qyra also accepts all standard postgres environment variables.

Server and networking

Core variables that control how the Qyra server runs, how it's reached, and how sessions and cookies behave.

Licensing

Query limits and behavior

Control how many rows a query can return, page sizes, exports, and chart-version retention.

Scheduler

Variables that control the scheduler worker and background cleanup jobs.

Headless browser

Configure the headless browser used for screenshots and PDF exports.

Personal access tokens

Variables that control PAT availability and lifetime.

Timezone and localization

Soft delete

Configure whether deletions are soft (recoverable) and for how long.

Custom metrics

UI customization

Replace default URLs and tweak in-product UI surfaces.

Feature toggles

Enable or disable individual product features across the instance.

Feature flags

Use these to force feature flags on or off across your deployment regardless of cloud-side targeting or per-organization overrides. Both variables accept a comma-separated list of feature-flag IDs (kebab-case strings — the flag IDs themselves, not env-var names). Useful for local dev flows where you want to toggle flags without touching targeting rules.

Athena

Snowflake

SMTP

This is a reference to all the SMTP environment variables that can be used to configure a Qyra email client.

[1] EMAIL_SMTP_PASSWORD or EMAIL_SMTP_ACCESS_TOKEN needs to be provided

SSO

These variables enable you to control Single Sign On (SSO) functionality.

S3

These variables allow you to configure S3 Object Storage, which is required to self-host Qyra.

Persistent download URLs

When enabled, CSV and dashboard ZIP exports return a stable Qyra-hosted URL (e.g. https://qyra.example.com/api/v1/file/{id}) instead of a direct S3 signed URL. Each time this URL is accessed, Qyra generates a short-lived S3 signed URL and redirects to it — so the underlying URL never goes stale and download links survive IAM credential rotation.

The variables below act as instance-wide defaults. Organization admins can override them per organization (and per channel) from Settings → Organization → Exporting. See Configuring download link expiration.

Cache

Logging

Prometheus

OpenTelemetry tracing

See Configure OpenTelemetry tracing for setup, exporter selection, and sampling behaviour.

Security

Analytics & Event Tracking

RudderStack product telemetry is enabled by default on self-hosted deployments and points at https://analytics.qyraflow.com. For the full payload, disable and redirect options, and the security-review checklist, see Data flows and telemetry.

AI Analyst

Enterprise-only. For setup steps (which provider to pick, how to point at an LLM gateway, how to enable verified answers), see AI agents. The tables below are the exhaustive variable reference.

The AI Analyst supports multiple providers. Provide credentials for the provider set in AI_DEFAULT_PROVIDER. OpenAI and Anthropic are the most tested. For which provider to pick and end-to-end setup, see AI agents.

OpenAI Configuration

Anthropic Configuration

Azure AI Configuration

OpenRouter Configuration

AWS Bedrock Configuration

Supported Models

OpenAI: gpt-5.1, gpt-5.2 (default)

Anthropic: claude-sonnet-4-5, claude-haiku-4-5, claude-sonnet-4

AWS Bedrock: claude-sonnet-4-5, claude-haiku-4-5, claude-sonnet-4

Slack Integration

These variables enable you to configure the Slack integration.

dbt

Configure how Qyra runs the dbt subprocess during project compilation.

GitHub Integration

These variables enable you to configure Github integrations

GitLab Integration

These variables enable you to configure the GitLab integration for dbt project sync.

Microsoft Teams Integration

These variables enable you to configure Microsoft Teams integration.

Google Cloud Platform

These variables enable you to configure Google Cloud Platform integration.

Embedding

Enterprise-only. For setup steps and how the allow-list of iframe origins works, see embedding.

Custom roles

Enterprise-only. See custom roles for setup.

Service account

Enterprise-only. See service accounts for setup.

SCIM

Enterprise-only. See SCIM for setup, including the required AUTH_ENABLE_OIDC_TO_EMAIL_LINKING companion when combining SCIM with SSO.

Sentry

These variables enable you to configure Sentry for error tracking.

Intercom & Pylon

These variables enable you to configure Intercom and Pylon for customer support and feedback.

Kubernetes

These variables enable you to configure Kubernetes integration.

Organization appearance

These variables allow you to customize the default appearance settings for your Qyra instance's organizations. This color palette will be set for all organizations in your instance. You can't choose another one while these env vars are set.

Pre-aggregates

Enterprise-only. For setup steps and the required pre-aggregate worker deployment, see pre-aggregates.

Data apps runtime

Enterprise-only. Sandboxes execute through E2B. For setup steps (coding-agent choice, model provider, S3 bucket, sandbox provider), see data apps.

APPS_CODING_AGENT=codex supports GPT-5.6 Sol, Terra, and Luna, with Terra as the default. When AI_DEFAULT_PROVIDER=bedrock, Qyra runs those models through Amazon Bedrock instead of OpenAI directly. AI_DEFAULT_PROVIDER also controls AI Analyst; APPS_CODING_AGENT affects only Data apps.

Managed agent

Enterprise-only. Runs scheduled AI agent tasks on a cron. See the managed agent section on the AI agents setup page for context.

MCP

Enterprise-only. For setup steps, connecting AI assistants, and network requirements, see MCP.

Metrics SQL API

Postgres wire protocol endpoint for the semantic layer. See Metrics SQL API.

NATS worker

Optional NATS-backed query workers. When enabled, Qyra routes query execution to dedicated NATS worker pods instead of running queries on the main API server. Enable at least one warehouse worker to process the routed queries.

Initialize instance Enterprise

When a new Qyra instance is created, and there are no orgs and projects. You can initialize a new org and project using ENV variables to simplify the deployment process. See the pricing page for what each plan includes. Only Databricks project types and GitHub dbt configuration are supported.

Initialization is skipped once an organization and project exist — on subsequent restarts, only the update instance call is made.

AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true

Update instance

On server start, we will check the following variables, and update some configuration of the organization or project. If multiple organizations or projects exist, you must set LD_SETUP_ORGANIZATION_UUID and/or LD_SETUP_PROJECT_UUID to target a specific one.

Initialize multiple projects

Set LD_SETUP_PROJECTS to a JSON array to provision multiple projects at once. This is a drop-in replacement for the single-project LD_SETUP_PROJECT_* variables described in Initialize instance — when LD_SETUP_PROJECTS is set, the legacy LD_SETUP_PROJECT_* and LD_SETUP_GITHUB_* variables are ignored.

On every boot, Qyra matches each entry to an existing project by its name: new names are created, existing names are updated in place.

Multi-project setup supports Databricks project types and GitHub dbt configuration.

Required companion variables

The admin, organization, and API key variables from Initialize instance still apply. LD_SETUP_ADMIN_EMAIL is required — without it, LD_SETUP_PROJECTS is ignored.

Schema

LD_SETUP_PROJECTS must be a JSON array. Each entry has the following shape:

Databricks warehouse fields

GitHub dbt connection fields

Example

export LD_SETUP_ADMIN_EMAIL="admin@example.com"
export LD_SETUP_PROJECTS='[
  {
    "name": "Sample Project Alpha",
    "warehouseConnection": {
      "type": "databricks",
      "serverHostName": "alpha.cloud.databricks.com",
      "httpPath": "/sql/1.0/warehouses/abc123",
      "database": "alpha_db",
      "personalAccessToken": "dapi_alpha_fake_token"
    },
    "dbtConnection": {
      "type": "github",
      "authorization_method": "personal_access_token",
      "personal_access_token": "ghp_fake_alpha_token",
      "repository": "myorg/alpha-repo",
      "branch": "main",
      "project_sub_path": "/"
    }
  },
  {
    "name": "Sample Project Beta",
    "warehouseConnection": {
      "type": "databricks",
      "serverHostName": "beta.cloud.databricks.com",
      "httpPath": "/sql/1.0/warehouses/def456",
      "database": "beta_db",
      "personalAccessToken": "dapi_beta_fake_token"
    },
    "dbtConnection": {
      "type": "github",
      "authorization_method": "personal_access_token",
      "personal_access_token": "ghp_fake_beta_token",
      "repository": "myorg/beta-repo",
      "branch": "main",
      "project_sub_path": "/"
    }
  }
]'

Databricks M2M OAuth example

Use a Databricks Service Principal when you want non-interactive, machine-to-machine authentication instead of a PAT. Qyra exchanges the client_id + client_secret for an access token automatically on the first compile and refreshes it as needed — no user interaction is required.

export LD_SETUP_ADMIN_EMAIL="admin@example.com"
export LD_SETUP_PROJECTS='[
  {
    "name": "Sales (Databricks M2M)",
    "warehouseConnection": {
      "type": "databricks",
      "serverHostName": "dbc-xxxx.cloud.databricks.com",
      "httpPath": "/sql/1.0/warehouses/abc123",
      "catalog": "qyra_prod",
      "database": "sales",
      "authenticationType": "oauth_m2m",
      "oauthClientId": "00000000-0000-0000-0000-000000000000",
      "oauthClientSecret": "dose...secret..."
    },
    "dbtConnection": {
      "type": "github",
      "authorization_method": "personal_access_token",
      "personal_access_token": "ghp_...",
      "repository": "myorg/dbt-sales",
      "branch": "main",
      "project_sub_path": "/"
    }
  }
]'

If you already have an M2M Service Principal configured for dbt, the field names are different. Map your dbt profile fields to Qyra's warehouseConnection like this:

Validation

LD_SETUP_PROJECTS is parsed and validated at boot. Qyra will fail to start with a descriptive error if any of the following are true:

Migrating from LD_SETUP_PROJECT_*

LD_SETUP_PROJECTS replaces the single-project LD_SETUP_PROJECT_NAME, LD_SETUP_PROJECT_HOST, LD_SETUP_PROJECT_HTTP_PATH, LD_SETUP_PROJECT_PAT, LD_SETUP_PROJECT_SCHEMA, LD_SETUP_PROJECT_CATALOG, LD_SETUP_PROJECT_COMPUTE, LD_SETUP_GITHUB_*, and LD_SETUP_DBT_VERSION variables. When both are set, LD_SETUP_PROJECTS takes precedence and the legacy variables are ignored.

To migrate:

1. Move your existing project config into a JSON object (use the existing project's exact name so it is updated in place rather than recreated).
2. Set LD_SETUP_PROJECTS to a single-element array containing that object.
3. Remove the legacy LD_SETUP_PROJECT_* and LD_SETUP_GITHUB_* variables from your deployment.

Declare user attributes

Set LD_SETUP_USER_ATTRIBUTES to a JSON array to declare user attributes and their group-value mappings as instance config. Qyra reconciles the array on every deploy, so you no longer need a manual post-deploy API or CLI step to (re)apply attributes after a release.

On every boot, Qyra matches each entry to an existing user attribute by its name: new names are created, existing names are updated in place. Attributes that are not present in the array are left untouched — this reconcile is non-destructive and never deletes attributes you created in the UI.

Schema

Each entry in the array has the following shape:

Example

LD_SETUP_USER_ATTRIBUTES='[
  {
    "name": "region",
    "description": "sales region access",
    "attributeDefault": ["US", "CA"],
    "groups": [
      { "group": "EMEA Analysts", "values": ["UK", "DE"] }
    ]
  }
]'

Group resolution

Group bindings are resolved by group name because group UUIDs aren't known at deploy time — groups provisioned via SCIM are created by your IdP, not by Qyra.

If a group name in groups doesn't match any existing group at the time the deploy runs (for example, because SCIM hasn't synced it yet), Qyra logs a warning and skips that mapping rather than failing the deploy. The mapping is retried on the next deploy, so once the group exists the binding reconciles automatically.

Per-user mappings

LD_SETUP_USER_ATTRIBUTES only supports group-based mappings. Per-user (by-email) values still need to be assigned through the UI or API.

Declare group → project access

Set LD_SETUP_GROUP_PROJECT_ACCESS to a JSON array to declare group → project role assignments as instance config. Qyra reconciles the array on every deploy, so you no longer need to re-apply group access through the UI or API after each release. This is the project-access equivalent of LD_SETUP_USER_ATTRIBUTES.

On every boot, Qyra matches each entry to a group and project, then either creates the access, updates it if the role differs, or leaves it untouched when it already matches. Group accesses that are not present in the array are left untouched — this reconcile is non-destructive and never removes access you assigned in the UI.

This is especially useful for instances that provision groups via SCIM: SCIM group UUIDs aren't known at deploy time, so this lets you declare role mappings by group name once and have them applied automatically as groups sync from your IdP.

Schema

Each entry in the array has the following shape:

Example

LD_SETUP_GROUP_PROJECT_ACCESS='[
  {
    "groupName": "Core Data Developer",
    "projectName": "Production",
    "role": "developer"
  },
  {
    "groupName": "Data Analyst",
    "projectUuid": "abc-123",
    "role": "PII Analyst"
  }
]'

Group, project, and role resolution

• Groups are resolved by groupName because group UUIDs aren't known at deploy time when groups are provisioned via SCIM.
• Projects are resolved by projectUuid when set, otherwise by projectName.
• Roles are resolved as a system role first; if the value doesn't match a system role, Qyra looks up a custom role with that name.

If a group, project, or custom role can't be resolved at the time the deploy runs (for example, because SCIM hasn't synced the group yet), Qyra logs a warning and skips that entry rather than failing the deploy. The entry is retried on the next deploy, so once the group, project, or role exists the access reconciles automatically.

Malformed JSON or entries that fail schema validation (e.g. missing groupName, or neither projectName nor projectUuid) throw at boot time so configuration errors surface before the instance starts.