Skip to main content

DIAL Deep Research environment variables

This reference lists backend 0.4.0 deployment settings for platform engineers familiar with the configuration overview. Defaults come from the released settings model and environment reads. Per-application sources, prompts, and limits belong in application properties.

Server and DIAL connection​

VariableDefaultDescription
DIAL_URL—Required HTTP(S) URL of DIAL Core, used for model calls, application properties, files, and deployment-mode MCP.
APP_HOST0.0.0.0HTTP bind address.
APP_PORT5000HTTP bind port. Core's registered endpoint addresses must use the reachable port.
DIAL_APP_NAMEdeep-researchApplication name used for logging and SDK telemetry. Does not rename the fixed completion deployment.
HEARTBEAT_INTERVAL5SSE heartbeat interval in seconds; integer, at least 1.
LLM_CACHE_POLICY—Optional availability-priority or cache-priority, sent as X-DIAL-CACHE-POLICY on model calls. Unset sends no policy header.
MAX_CONTEXT_IMAGES50Maximum image content blocks in an LLM request; integer, at least 1.

Sources: server settings, DIAL and image settings, and cache-policy header.

LLM_CACHE_POLICY controls Core's retry routing; it does not enable prompt caching. Core's model deployment must support and enable the appropriate caching behavior. See Prompt caching.

The backend has no static DIAL_API_KEY deployment setting. Its SDK propagates the current request's key to Core calls. REMOTE_DIAL_URL, REMOTE_DIAL_API_KEY, and the CLI's DIAL_API_KEY belong to upstream development scripts, not this runtime settings model.

Model deployment mappings​

Every model enum has an optional LLM_MODELS_<ENUM_NAME> override. The value is a DIAL Core deployment ID, not a provider credential or URL.

VariableDefaultDescription
LLM_MODELS_GPT_5_6_TERRAgpt-5.6-terra-2026-07-09Mapping used by the backend's default model configuration.
LLM_MODELS_GPT_5_6_LUNAgpt-5.6-luna-2026-07-09Mapping for this enum member when selected in code.
LLM_MODELS_GPT_5_4_2026_03_05gpt-5.4-2026-03-05Mapping for this enum member when selected in code.
LLM_MODELS_GPT_5_4_2026_03_05_REASONINGgpt-5.4-2026-03-05-reasoningMapping for this enum member when selected in code.
LLM_MODELS_GPT_5_2_2025_12_11gpt-5.2-2025-12-11Mapping for this enum member when selected in code.
LLM_MODELS_CLAUDE_OPUS_4_6anthropic.claude-opus-4-6-v1Mapping for this enum member when selected in code.
LLM_MODELS_CLAUDE_SONNET_4_6anthropic.claude-sonnet-4-6Mapping for this enum member when selected in code.

The complete mapping and default model selection are in llm.py. Setting an override for another enum member does not select it. The released preparation agent constructs the default model configuration.

A mapping changes only the deployment ID. Every model call still sends reasoning_effort: none by default and medium in the review steps. The mapped deployment must accept that parameter. See the request parameters and review-step models.

Example environment fragment:

DIAL_URL=http://core:8080
LLM_MODELS_GPT_5_6_TERRA=<CORE_MODEL_DEPLOYMENT_ID>

Logging​

VariableDefaultDescription
LOG_LEVELINFORoot and managed third-party logger level.
DEEP_RESEARCH_LOG_LEVELINFOIndependent level for dial_deep_research loggers.
LOG_FORMATFormat belowPython logging format, including SDK/OpenTelemetry context.
LOG_DATE_FORMAT%Y-%m-%d %H:%M:%STimestamp format.
LOG_PAYLOADSfalseEnables payload debug logging. Disabled excludes payload content at every level.
LOG_PAYLOADS_MAX_LENGTH2000Maximum characters per logged payload string; integer, at least 1.

Both level settings accept DEBUG, INFO, WARNING, ERROR, and CRITICAL, normalized to uppercase. The default LOG_FORMAT is:

%(levelprefix)s | %(asctime)s | %(process)d | %(name)s | %(otel_context)s%(message)s

Defaults and the payload policy are defined in settings.py.

Warning

Payload logging can expose research questions, retrieved content, and client prompts. The source limits this mode to local development; keep LOG_PAYLOADS=false in shared environments.

Optional channels and tracing​

VariableDefaultDescription
ENABLE_PLAYGROUND_CHANNELfalseRegisters deep-research-playground, a tool-calling agent without the preparation/research workflow. Uses the instance's application properties.
ENABLE_ANNOTATIONS_DEMOfalseRegisters deep-research-annotations-demo, which returns a fixed report citing two PDFs attached by the caller, each at least three pages. It reads no application properties, runs no research, and calls no model.
OPIK_TRACING_ENABLEDfalseEnables local Opik tracing. Requires the optional tracing dependency extra.
OPIK_PROJECT_NAMEdeep-researchOpik project name; non-empty string.

The flags are defined in settings.py; optional deployments are registered in factory.py. The demo's inputs are described in its completion and the README; with other attachments, it replies with what to attach.

The standard image installs main dependencies without the optional tracing extra. Enabling Opik without it raises an error during startup. See the Docker dependency installation, optional dependency, and startup tracing check.

SDK telemetry is configured with DIAL_APP_NAME as its service name, tracing, and metrics. Its exporter settings are SDK/OpenTelemetry settings rather than additional fields in the backend's settings model. See SDK initialization.

Direct MCP connection secrets​

Direct-mode connections use deployment-defined variable names, referenced by mcp_servers[].connection. Each variable holds one JSON object containing url and a non-empty api_key. There is no fixed MCP_URL or MCP_API_KEY runtime setting.

RESEARCH_MCP_CONNECTION={"url":"https://<MCP_HOST>/mcp","api_key":"<MCP_API_KEY>"}

The application property is "connection": "$env:{RESEARCH_MCP_CONNECTION}". A missing variable, inline connection value, or $env:{VAR|default} form fails validation. See the placeholder validator and MCP connection modes.

Further reading​