How DIAL Chat is configured

DIAL Chat is configured entirely through environment variables on its BFF (chat-api). This page explains how those variables are read and validated, lists the few that every deployment needs, and shows which page documents each group. It is for platform engineers who deploy Chat 1.x; it assumes you have read the DIAL Chat overview.

How variables are read

• Validated at startup. The BFF validates every variable when it boots, so a missing or malformed value stops the container at once instead of failing at the first request.
• Read once. A change takes effect on the next restart of chat-api.
• Server-only or client-visible. Server-only variables never leave the BFF. Client-visible ones are sent to the browser through GET /api/v1/client-config, so never put a secret in them.
• Local files. For local development, .env.local takes precedence over .env. The annotated list of every variable is apps/chat-api/.env.template in the DIAL Chat repository.

Required variables

Variable	Description
AUTH_SESSION_SECRET	The 32-byte key that encrypts the session cookie, as 64 hexadecimal characters.
AUTH_CALLBACK_BASE_URL	The public base URL of the BFF, used to build the OpenID Connect redirect URIs.
One identity provider	At least one provider, registered by setting its AUTH_<PROVIDER>_CLIENT_ID. Without one, Chat starts but nobody can sign in. See Authentication.

In practice, every deployment also sets DIAL_CORE_URL and THEMES_CONFIG_URL.

Minimal example

From dial-docker-compose-advanced/dial-2.x/docker-compose-base.yml, for local evaluation with Keycloak:

chat:
  image: epam/ai-dial-chat:<VERSION>
  environment:
    PORT: "3000"
    API_PREFIX: "api"
    CORS_ORIGIN: "http://0.0.0.0:3000"
    AUTH_SESSION_SECRET: "${AUTH_SESSION_SECRET}"
    AUTH_CALLBACK_BASE_URL: "http://0.0.0.0:3000"
    AUTH_KEYCLOAK_CLIENT_ID: "dial-chat"
    AUTH_KEYCLOAK_SECRET: "${AUTH_KEYCLOAK_SECRET}"
    AUTH_KEYCLOAK_HOST: "http://keycloak:8080/realms/dial"
    AUTH_KEYCLOAK_DIAL_ROLES_FIELD: "resource_access.dial-chat.roles"
    AUTH_COOKIE_SECURE: "false"
    DIAL_CORE_URL: "http://core:8080"
    THEMES_CONFIG_URL: "http://themes:8080"

warning

AUTH_COOKIE_SECURE: "false" is for local HTTP only. Keep the default, true, for every HTTPS deployment.

Variables by group

Page	What it covers
Server and DIAL Core	Port and prefix, CORS, the DIAL Core connection, the themes service, the outbound proxy, the version label, and the custom Core API bridge
Authentication	The session cookie, each identity provider, roles claims, bearer-token authentication, and the DIAL Core OAuth allowlist
Features and UI	ENABLED_UI_FEATURES, feature flags, the Catalog, the start screen, announcements, celebrations, Projects, and Scheduled Tasks
Models and generation	The default deployment, the Responses API, background generation, the utility model, speech-to-text, and prompt overrides
Files and limits	Upload, archive, skill, and project limits, and file and generation timeouts
Security and embedding	Content Security Policy, iframe origins, visualizers, and MCP Apps
Observability	Logging, OpenTelemetry traces, logs, and metrics

The overlay variables, OVERLAY_ENABLED and OVERLAY_SANDBOX_ENABLED, are described with the Chat Overlay.