Skip to main content
Version: v2026.0.0

Environment variables reference

All environment variables accepted by uxopian-ai and uxopian-gateway. Variables marked with a default are optional; variables with no default are required when the feature is used.

uxopian-ai environment variables​

Application​

VariableDefaultDescription
APP_BASE_URL(empty)Public base URL of the application. Used in generated links.
UXOPIAN_AI_PORT8080HTTP port for the application server
CONTEXT_PATH(empty)Servlet context path prefix (e.g., /ai)
SPRING_PROFILES_ACTIVE(empty)Active Spring profiles. Set to dev to disable authentication.
TOOLS_ENABLEDtrueSet to false to disable all tool execution
JAVA_OPTS(empty)JVM options (e.g., -Xmx768m -Xms512m)

Internal authentication​

VariableDefaultDescription
INTERNAL_AUTH_JWT_SECRET(none — required)HS256 secret shared with the gateway, at least 32 bytes (openssl rand -base64 48). Since 2026.0.0 uxopian-ai refuses to start without it, in every profile, dev included. Set the same value on the gateway.
INTERNAL_AUTH_JWT_ISSUERuxopian-gateway-internalExpected iss claim of the gateway assertion.

OpenSearch​

VariableDefaultDescription
OPENSEARCH_HOSTlocalhostOpenSearch hostname
OPENSEARCH_PORT9200OpenSearch port
OPENSEARCH_SCHEMEhttpConnection scheme (http or https)
OPENSEARCH_USERNAME(empty)OpenSearch username (if auth enabled)
OPENSEARCH_PASSWORD(empty)OpenSearch password (if auth enabled)

LLM providers​

VariableDefaultDescription
LLM_DEFAULT_PROVIDERopenaiProvider of the usage profile auto-created for a connection provider that has none. No longer a fallback at call time.
LLM_DEFAULT_MODELgpt-5.1Model of that auto-created usage profile
LLM_DEFAULT_PROMPTbasePromptDefault base prompt ID (replaced, for its calls, by the prompt of a usage profile)
LLM_CONTEXT_SIZE10Number of previous requests included in each LLM call
LLM_DEBUGfalseEnable verbose LLM request/response logging
OPENAI_API_KEY(empty)OpenAI API key
ANTHROPIC_API_KEY(empty)Anthropic API key
AZURE_OPENAI_API_KEY(empty)Azure OpenAI API key
GEMINI_API_KEY(empty)Google Gemini API key
MISTRAL_API_KEY(empty)Mistral AI API key
HUGGINGFACE_API_KEY(empty)HuggingFace API key
NUEXTRACT_API_KEY(empty)NuExtract API key
BEDROCK_AWS_ACCESS_KEY(empty)AWS access key for Bedrock
BEDROCK_AWS_SECRET_KEY(empty)AWS secret key for Bedrock

The limits and the retention of the files sent to models (llm.inline.max-size, llm.document.max-size, llm.files.retention) are described in the configuration reference.

Plugins​

VariableDefaultDescription
PLUGINS_ROOT_PATHplugins/Path to the directory containing plugin JARs
PLUGINS_TOOLS_ENABLED_TAGSflowerdocs,files,interactionComma-separated @ToolService(tags=…) list. Since 2026.0.0-ft5, this no longer gates which tools get registered at startup — every tool in every plugin JAR present in plugins/ is always registered, regardless of this value. It now only seeds the tool-tag whitelist of the usage profile auto-created the first time a connection provider is used (empty = allowAllTools). See Plugin system — Filtering tools by tag. Do not whitelist more than one of flowerdocs, alfresco, filenet on the same usage profile — they all expose overlapping document search/read/redact operations for different ECM backends, and exposing more than one confuses the LLM about which to call. Pick exactly one, e.g. flowerdocs,files,interaction (default), alfresco,files, filenet,files,interaction, or files alone if no ECM backend is needed.

Integration connectors​

VariableDefaultDescription
RENDITION_BASE_URL(empty)ARender base URL. Required if the ARender plugin is deployed. Also relayed at <app>/rendition/ for the human review screen.
FILECONNECTOR_FILESYSTEM_ROOT(empty — connector off)Root folder of the filesystem file connector (<root>/<tenant>/). The application fails to start if it is not a readable and writable folder. Required to accept persist: true attachments.
FILECONNECTOR_FILESYSTEM_ALLOWEDEXTENSIONSpdf,png,jpg,jpeg,tif,tiffExtensions the filesystem connector accepts (comma-separated)
FD_WS_URL(empty)FlowerDocs core web service URL (e.g. http://<flowerdocs-endpoint>/core/). Required if the FlowerDocs plugin is deployed.
ALFRESCO_BASE_URL(empty)Alfresco REST API v1 base URL. Required if the Alfresco plugin is deployed (via PLUGINS_TOOLS_ENABLED_TAGS=alfresco,…).
ALFRESCO_LEGACY_BASE_URL(auto-derived)Base URL for Alfresco legacy Web Script endpoints. Auto-derived from ALFRESCO_BASE_URL when not set (e.g., https://host/alfresco-api → https://host/alfresco; https://host/alfresco/api → https://host/alfresco/s). Set explicitly only if the auto-derivation does not match your deployment.
ALFRESCO_CMM_ENABLEDfalseEnable Alfresco Custom Content Model lookup. When disabled, the LLM sees only the built-in cm:* system properties.

Code sandbox​

Optional: code modules run in a separate uxopian-code-sandbox service. These names are the Spring relaxed-binding forms of the code-sandbox.* properties described in the configuration reference.

VariableDefaultDescription
CODESANDBOX_URL(empty — sandbox off)Base URL of uxopian-code-sandbox. Without it, no code tool is offered.
CODESANDBOX_SECRET(empty)Shared secret used to call the sandbox
CODESANDBOX_CALLERNAMEuxopian-aiCaller name presented to the sandbox
CODESANDBOX_CAPABILITYPROFILEuxoaiCapability profile the code runs with
CODESANDBOX_MAXACTIVESESSIONS16Executions allowed at once

Script security scan​

Used by the admin-managed scripts feature (2026.0.0-ft4). Optional — without a configured provider, scripts can still be created, edited, and force-published, but the security scan is disabled.

VariableDefaultDescription
SCRIPT_SCAN_LLM_PROVIDER(empty)ID of a configured LLM provider used to run the script security scan. Required to enable scanning.
SCRIPT_SCAN_LLM_MODEL(empty)Model used for the scan; falls back to the provider's default model when blank.

Security​

VariableDefaultDescription
app.security.secret-key(dev default)AES/GCM encryption key for stored API secrets. Set a unique value in production.

MCP (Model Context Protocol)​

Since 2026.0.0-ft3, MCP servers are registered from the admin UI — see Managing MCP servers. The environment variable below is retained only for the legacy single-server boot-time configuration and is disabled by default.

VariableDefaultDescription
MCP_SSE_URL(empty)Legacy boot-time MCP SSE endpoint URL, read only when the commented block in mcp-server.yml is re-enabled. For runtime management, prefer the admin UI.

Hazelcast​

VariableDefaultDescription
HAZELCAST_MULTICAST_ENABLEDtrueMulticast discovery, local (non-Kubernetes) mode only. Hazelcast auto-detection is always disabled since 2026.0.0: set this to false for single-node or Docker Compose setups on a shared network.
HAZELCAST_KUBERNETES_ENABLEDfalseEnable Kubernetes-based Hazelcast discovery
HAZELCAST_KUBERNETES_SERVICE_DNSai-standalone-headlessKubernetes headless service DNS
HAZELCAST_KUBERNETES_NAMESPACEdefaultKubernetes namespace

uxopian-gateway environment variables​

The gateway is configured primarily via the mounted gateway-application.yaml file. Environment variables for the gateway control image selection and are injected by the compose .env file:

VariableDefaultDescription
REGISTRYartifactory.arondor.cloud:5001Docker registry host for Artifactory-based image pull. Not used when switching to Cloudsmith images (see Registry access).
UXOPIAN_VERSION2026.0.0Version tag for uxopian-gateway and uxopian-ai images

In the gateway gateway-application.yaml, the URIs for backend services are hardcoded Docker Compose service names (e.g., http://uxopian-ai:8080).

OpenSearch environment variables​

VariableDefaultDescription
OPENSEARCH_VERSION3.0.0OpenSearch image version (used in compose .env)
DISABLE_SECURITY_PLUGIN—Set to true to disable OpenSearch security plugin (development only)
DISABLE_INSTALL_DEMO_CONFIG—Set to true to skip demo config installation
discovery.type—Set to single-node for single-node deployments
OPENSEARCH_JAVA_OPTS—JVM options for OpenSearch (e.g., -Xms512m -Xmx512m)