Quick Apps Frontend configuration

The Quick Apps Frontend is the visual editor for Quick App settings. Its image is the DIAL Chat BFF, chat-api, with the editor's static build on top, so it takes the Chat BFF's environment variables. This reference lists the ones the editor relies on, and the editor's own options. It is for platform engineers who deploy the editor. It assumes you know how Quick Apps is configured.

• The image is amd64-only and listens on port 5000.
• The health check is /<API_PREFIX>/health, by default /api/health.
• Every Chat BFF variable not listed here works as it does for Chat. See DIAL Chat configuration.

Server and DIAL Core

Variable	Default	Description
DIAL_CORE_URL	—	Required. The base URL of the DIAL Core API.
PORT	5000	The port the server listens on.
API_PREFIX	api	The path prefix of the API and health-check routes.

Session

Variable	Default	Description
AUTH_SESSION_SECRET	—	Required. 64 hex characters that sign and encrypt the session cookie, for example from openssl rand -hex 32.
AUTH_SESSION_PREV_SECRET	—	The previous secret. While both are set, sessions signed with either are accepted, so you can rotate without downtime.
AUTH_CALLBACK_BASE_URL	—	Required. The editor's own origin, such as https://quickapps.example.com.
CORS_ORIGIN	—	Required. The origins allowed to call the editor's API cross-origin; usually the same as AUTH_CALLBACK_BASE_URL.
AUTH_POST_LOGOUT_REDIRECT_URI	AUTH_CALLBACK_BASE_URL	Where the browser lands after logout. Set it to the same value as AUTH_CALLBACK_BASE_URL.
AUTH_SESSION_COOKIE_NAME	__Host-quickapps.sess	The session cookie name, kept apart from Chat's chat.* cookies.
AUTH_TRANSACTION_COOKIE_NAME	__Host-quickapps.tx	The cookie used only during sign-in.
AUTH_LEGACY_COOKIE_NAMES	—	Comma-separated cookie names to expire. Set it when you rename a cookie on an existing deployment.
AUTH_COOKIE_SECURE	true	Set false only for local HTTP. It drops the __Host- prefix from the cookie names. See DIAL Chat authentication.

HTTP 431 after an upgrade

431 Request Header Fields Too Large at sign-in means the browser sends too many cookies to this host. It happens when an older deployment on the same host left its cookies, such as the next-auth.* cookies of editors before 0.3.0. The server rejects the request before it can clear them.

• For local testing, clear the host's cookies in the browser.
• In production, set AUTH_LEGACY_COOKIE_NAMES to the old cookie names, so the first request that gets through expires them. Also give the reverse proxy some header-size headroom, such as nginx large_client_header_buffers.

Identity provider

Configure at least one sign-in provider: Keycloak, Microsoft Entra ID, Google, Auth0, Okta, Amazon Cognito, or GitLab. The variables are the Chat BFF's, per provider; see DIAL Chat authentication. For Keycloak:

Variable	Description
AUTH_KEYCLOAK_HOST	The realm's base URL, such as https://keycloak.example.com/realms/dial.
AUTH_KEYCLOAK_CLIENT_ID	The OAuth client registered for the editor in that realm.
AUTH_KEYCLOAK_SECRET	That client's secret. Keep it out of checked-in files.

• Register <AUTH_CALLBACK_BASE_URL>/api/v1/auth/callback/<provider> as the client's redirect URI, such as https://quickapps.example.com/api/v1/auth/callback/keycloak.
• The editor calls DIAL Core with the user's token. If the provider in DIAL Core sets audience, the editor's tokens must carry it too.

Themes

Variable	Default	Description
THEMES_CONFIG_URL	—	The base URL of DIAL Chat Themes; /config.json is added to it. When unset, the editor uses its default CSS variables.

Iframe embedding and CSP

Variable	Default	Description
ALLOWED_IFRAME_ORIGINS	—	Comma-separated origins allowed to frame the editor, through CSP frame-ancestors. List the exact DIAL Chat and DIAL Admin origins.
OVERLAY_ENABLED	—	Leave it unset unless the session cookie needs SameSite=None. It is Chat's overlay flag, not an editor setting.
CSP_MODE	report-only	Set enforce once report-only produces no violation reports.
ALLOWED_CONNECT_ORIGINS	—	Extra origins the page may call. Leave it empty: the editor calls only its own origin.

Default model

Variable	Default	Description
DEFAULT_DEPLOYMENT	—	The model selected for a new Quick App. When it is unset, or the user can't see it, the editor selects the first model that supports tools.

New apps get an orchestrator temperature of 0.5.

Editor options

The editor's own options go in CUSTOM_CLIENT_VARIABLES, a JSON object.

Key	Description
allowedOrigin	The origins allowed to exchange postMessage events with the editor: one origin, a comma-separated list, or a JSON array. List the exact Chat and DIAL Admin origins. Unset or * accepts any origin, which is unsafe outside local development.
dialChatHost	The DIAL Chat origin. The editor uses it when it detects that Chat embeds it.
dialAdminHost	The DIAL Admin origin. The editor's default host otherwise.
codeInterpreterEnabled	Offers the Code interpreter setting.
webFetchEnabled	Offers the Web fetch setting.
addAttachmentEnabled	Offers the Add attachment setting.

The three flags are off unless set to the boolean true; the string "true" counts as off. Turn on a flag only when its tool works in your deployment. For example, web fetch needs EXTERNAL_URL_FETCH_ENABLED on the backend.

CUSTOM_CLIENT_VARIABLES='{"allowedOrigin":["https://chat.example.com","https://admin.example.com"],"dialChatHost":"https://chat.example.com","dialAdminHost":"https://admin.example.com","codeInterpreterEnabled":true}'

The application name isn't configured: the host passes it as the applicationName query parameter of the editor URL. One editor deployment can therefore serve several applications. DIAL Chat passes the application type's display name, dial:applicationTypeDisplayName.

OpenTelemetry

OpenTelemetry is off by default, OTEL_SDK_DISABLED=true. To turn it on, set false and the standard OpenTelemetry SDK variables, such as OTEL_SERVICE_NAME and OTEL_EXPORTER_OTLP_ENDPOINT.

Host integration

A host page, such as DIAL Chat or DIAL Admin, drives the editor with postMessage. The editor accepts messages only from its parent window, and only from an origin in allowedOrigin.

Host to editor	Payload	Effect
TRIGGER_SAVE	{ general? }	Saves the app. general carries the host's name, description, icon, topics, and version, saved in the same request.
TRIGGER_AUTO_SAVE	{ ignoreDirty? }	Starts an auto-save.
RESET	—	Restores the values loaded when the editor opened.

Editor to host	Payload	Meaning
READY	—	The editor is mounted.
DIRTY_STATE	{ isDirty }	The form's unsaved state changed.
VALIDITY_STATE	{ isValid }	The form's validity changed.
SAVE_SUCCESS	{ updatedApp }, hasChanges	A save finished.
SAVE_ERROR	{ error }	A save failed, or validation blocked it.
AUTO_SAVE_COMPLETE	—	An auto-save finished.
HEIGHT_CHANGE	{ height }	The editor's height changed, so the iframe can resize.
REQUEST_APPLICATION_CREDENTIALS	{ appId }	The user asked to sign in to an agent's external services. Sent only when the host adds applicationCredentials=true to the editor URL.

The editor also auto-saves every 30 seconds while the form has unsaved changes, after the app's first save.

Further reading

• DIAL Core and DIAL Chat — register the editor URL and let Chat frame it
• Backend — the backend's environment variables
• DIAL Chat configuration: Authentication — OpenID Connect sign-in, sessions, and roles in Chat
• Identity providers — register identity providers and read claims from their tokens
• DIAL Chat Themes — the static service that holds Chat's branding