Skip to main content
Version: v2026.0.0

Configuration file reference

All configuration files for uxopian-ai are placed in the ./config/ directory on the host, mounted to /app/config inside the container. The application imports them at startup via application.yaml. This page documents every configuration key in every file.

application.yml​

Controls the base URL, server port, Spring profiles, and tool settings.

KeyEnv variableDefaultDescription
app.base-urlAPP_BASE_URL(empty)Public base URL for the application (used in generated links)
server.portUXOPIAN_AI_PORT8080HTTP port uxopian-ai listens on
server.servlet.context-pathCONTEXT_PATH(empty)Optional servlet context path prefix
tools.enabledTOOLS_ENABLEDtrueSet to false to disable all tool execution
plugins.root.pathPLUGINS_ROOT_PATHplugins/Directory scanned at startup for plugin JARs
plugins.tools.enabled-tagsPLUGINS_TOOLS_ENABLED_TAGSflowerdocs,files,interactionSince 2026.0.0-ft5, this no longer gates which tools get registered at startup — every @ToolService in every plugin JAR present in plugins/ is always registered. It now only seeds the default tool-tag whitelist on an auto-created usage profile (empty = allowAllTools). See Plugin system.
spring.profiles.activeSPRING_PROFILES_ACTIVE(empty)Active Spring profiles. Add dev to disable auth.

Example:

app:
base-url: ${APP_BASE_URL:}

server:
port: ${UXOPIAN_AI_PORT:8080}

tools:
enabled: ${TOOLS_ENABLED:true}

Gateway-signed request authentication​

Since 2026.0.0-ft5, requests can carry a gateway-issued X-Gateway-Auth assertion instead of bare X-User-* headers.

The secret is mandatory since 2026.0.0

internal-auth.jwt.secret is required in every profile, dev included: ai-standalone refuses to start without it. Before, a missing secret simply switched verification off and let any caller choose its tenant and roles with bare X-User-* headers. Every non-Helm deployment (Docker, plain Java, Compose) must now set INTERNAL_AUTH_JWT_SECRET (at least 32 bytes) on ai-standalone and on the gateway, with the same value. The Helm chart already required it; it also accepts an existing Secret through appConfig.internalAuth.existingSecret (the Secret must carry the key INTERNAL_AUTH_JWT_SECRET). With the dev profile the assertion itself is still not verified.

An assertion without an exp claim is refused (401). The official gateway always sets one (30 s lifetime by default), so only hand-made tokens are affected.

KeyEnv variableDefaultDescription
internal-auth.jwt.secretINTERNAL_AUTH_JWT_SECRET(none — required)HS256 shared secret, at least 32 bytes, must be byte-for-byte identical to the gateway's own internal-auth.jwt.secret. Generate with openssl rand -base64 48.
internal-auth.jwt.issuerINTERNAL_AUTH_JWT_ISSUERuxopian-gateway-internalExpected iss claim on the incoming assertion.
internal-auth.jwt.clock-skew-secondsINTERNAL_AUTH_JWT_CLOCK_SKEW_SECONDS5Allowed clock drift when validating the assertion's expiry.

Rotating the secret requires rolling both services close together — expect 401 responses between the two rollouts until both are running the new value.

opensearch.yml​

OpenSearch connection settings.

KeyEnv variableDefaultDescription
opensearch.hostOPENSEARCH_HOSTlocalhostOpenSearch host
opensearch.portOPENSEARCH_PORT9200OpenSearch port
opensearch.schemeOPENSEARCH_SCHEMEhttpConnection scheme (http or https)
opensearch.usernameOPENSEARCH_USERNAME(empty)Username for authenticated OpenSearch
opensearch.passwordOPENSEARCH_PASSWORD(empty)Password for authenticated OpenSearch
opensearch.index-prefixOPENSEARCH_INDEX_PREFIXuxopian-aiPrefix used in index names: {tenant}-{prefix}-{base}

Example:

opensearch:
host: ${OPENSEARCH_HOST:localhost}
port: ${OPENSEARCH_PORT:9200}
scheme: ${OPENSEARCH_SCHEME:http}
username: ${OPENSEARCH_USERNAME:}
password: ${OPENSEARCH_PASSWORD:}
Removed in 2026.0.0

opensearch.force-refresh-index (OPENSEARCH_FORCE_REFRESH_INDEX) no longer exists. If it is still set in your files or Helm values (appConfig.openSearch.forceRefresh), it is harmless but does nothing.

llm-clients-config.yml​

LLM provider configurations, default provider/model, and context size.

Default LLM settings​

KeyEnv variableDefaultDescription
llm.default.providerLLM_DEFAULT_PROVIDERopenaiProvider written into the usage profile that is auto-created for a connection provider that has none. It is not a fallback at call time: a call whose prompt and usage profile name no provider fails.
llm.default.modelLLM_DEFAULT_MODELgpt-5.1Model written into that auto-created usage profile. If these two properties are unset, the profile takes the tenant's first LLM provider configuration and its default model.
llm.default.base-promptLLM_DEFAULT_PROMPTbasePromptDefault base prompt ID. A usage profile's own prompt replaces it for the calls of that profile (one base prompt per call); a missing or unpublished profile prompt falls back to this one, with a warning. Agents get no base prompt.
llm.context.sizeLLM_CONTEXT_SIZE10Number of previous requests included in each LLM call
llm.debug.enabledLLM_DEBUGfalseEnable verbose LLM request/response logging
llm.inline.max-size—5MBLargest inline base64 file accepted in a request. Beyond it: 413 PAYLOAD_TOO_LARGE, nothing is stored.
llm.document.max-size—20MBLargest file or document sent to a model; it also sets the multipart max-file-size (the whole multipart request is capped at 100 MB). A model or provider can lower it with maxDocumentSizeMb. Beyond it: 422 DOCUMENT_TOO_LARGE.
llm.files.retention—1dHow long the files sent with a request (inline contents and attachments converted to PDF) are kept so that a retry can send them again. A nightly job purges older files and marks their contents expired. 0 keeps nothing. Files sent with persist: true are not concerned.

The three llm.inline.max-size, llm.document.max-size and llm.files.retention keys have no environment variable of their own in the shipped files; set them in application.yml, or through Spring's relaxed binding (LLM_FILES_RETENTION=2d).

Whether a model reads documents is a flag on the model itself, documentSupported (default false), set in the model parameters of the LLM provider in the admin UI.

Provider configuration structure​

llm:
provider:
globals:
- provider: <provider-id>
defaultLlmModelConfName: <model-conf-name>
globalConf:
apiSecret: <api-key>
endpointUrl: <provider-url>
temperature: <float>
timeout: <duration>
maxRetries: <int>
extras:
<provider-specific-key>: <value>
llModelConfs:
- llmModelConfName: <name>
modelName: <actual-model-name>
multiModalSupported: <bool>
functionCallSupported: <bool>

Supported provider identifiers​

openai, anthropic, azure-openai, bedrock, gemini, mistral-ai, huggingface, ollama, nu-extract

Provider-specific extras​

ProviderExtra keysDescription
bedrockAwsRegion, AwsAccessKey, AwsSessionTokenAWS credentials and region
nu-extractproject, output, rasterizationDPI, enableThinking, thinkingTokenBudget, loopDetectionNuExtract runs on the NuMind platform — see NuExtract below.

Azure OpenAI (azure-openai) does not use extras. The modelName field is passed as the deployment name.

NuExtract​

Since 2026.0.0, a NuExtract model that receives a PDF runs a structured extraction job on the NuMind platform (endpoint https://bbox.nuextract.ai, which is also the default in the shipped example). The legacy call (https://nuextract.ai/api/projects/) is removed, together with the modelId extra and the model-id key: set the endpoint to https://bbox.nuextract.ai, drop modelId, and either set the project extra or start the prompt with the JSON template.

ExtraDescription
projectId of the NuMind project (starting with sprj_); its template and instructions replace the message's. Empty: the message carries the template, as JSON at its very start (e.g. {"invoiceNumber":"string","total":"number"}), optionally followed by instructions.
outputvalues, positions or values-and-positions (default). With positions alone a localization failure is raised; otherwise the values are returned without positions.
rasterizationDPIResolution the pages are read at: automatic, or 1 to 600.
enableThinkingtrue or false: let the model reason before answering.
thinkingTokenBudgetMost tokens the model may reason with when thinking is enabled.
loopDetectiontrue or false: stop the model when it repeats itself.
nu-extract:
api-key: ${NUEXTRACT_API_KEY:}
base-url: https://bbox.nuextract.ai
model-name: nuextract
supported-models:
- modelName: nuextract
extras:
project: sprj_your-numind-project-id

The answer is JSON, { "result": { ... }, "localization": { ... } }. The provider does not stream: POST /api/v1/requests/stream with a NuExtract model answers 422; use POST /api/v1/requests. A message without a document only tests the key (this is what the admin "test" does). The model temperature, seed and maximum tokens are sent to the job.

Tenant overrides​

llm:
provider:
tenants:
- tenantId: <tenant-id>
mergeStrategy: MERGE # MERGE | OVERWRITE | CREATE_IF_MISSING
providers:
- provider: <provider-id>
globalConf:
apiSecret: <tenant-specific-key>

prompts.yml​

Prompt template definitions.

note

Prompts live only as versioned documents in OpenSearch (see Managing prompts); base prompts are seeded once, at tenant creation, from prompts.globals below.

KeyDescription
prompts.globalsList of global prompt definitions (see structure below)

Prompt definition structure​

- id: <unique-id>
role: SYSTEM | USER | ASSISTANT
content: |
Thymeleaf template content...
[[${variable}]]
requiresMultiModalModel: false
requiresFunctionCallingModel: false
reasoningDisabled: false
defaultLlmProvider: "" # provider that answers this prompt (else the usage profile's)
defaultLlmModel: "" # model that answers this prompt (else the usage profile's)

metrics.yml​

Micrometer metrics and actuator configuration.

KeyDescription
management.elastic.metrics.export.enabledEnable/disable OpenSearch metrics export (default: true)
management.elastic.metrics.export.hostOpenSearch URL for metrics. Default reads from opensearch.* properties.
management.elastic.metrics.export.indexIndex name for metrics (default: micrometer-metrics)
management.elastic.metrics.export.auto-create-indexAuto-create metrics index (default: true)
management.endpoints.web.exposure.includeExposed actuator endpoints. Default: health,info — /actuator/loggers was removed from exposure in 2026.0.0-ft5, and management.endpoint.loggers.enabled is false as defense-in-depth. See Upgrade notes.
management.metrics.uxopian-ai.enableEnable custom uxopian-ai metrics (default: true)
management.metrics.enable.*Standard metric groups disabled by default: application, tomcat, logback, jvm, system, http, process, disk, executor

hazelcast.yml​

Hazelcast cluster configuration. Used by the gateway for session caching.

Since 2026.0.0, Hazelcast auto-detection is always disabled: only the explicit mechanisms below (Kubernetes discovery, or multicast when enabled) are used. A deployment that silently relied on auto-detection — for instance a Docker network without multicast and without Kubernetes mode — no longer forms a cluster. Set HAZELCAST_MULTICAST_ENABLED=false for single-node or Docker Compose setups on a shared network, so that a node never tries to join the cluster of another uxopian-ai.

KeyEnv variableDefaultDescription
hazelcast.cluster-name—uxopian-ai-clusterHazelcast cluster name
hazelcast.multicast.enabledHAZELCAST_MULTICAST_ENABLEDtrueMulticast discovery. Only applies in local (non-Kubernetes) mode.
hazelcast.kubernetes.enabledHAZELCAST_KUBERNETES_ENABLEDfalseEnable Kubernetes service discovery
hazelcast.kubernetes.service-dnsHAZELCAST_KUBERNETES_SERVICE_DNSai-standalone-headlessKubernetes headless service DNS name
hazelcast.kubernetes.namespaceHAZELCAST_KUBERNETES_NAMESPACEdefaultKubernetes namespace for discovery

File connector, review tasks and rendition​

Properties of application.yml (or any file imported by it) for the file connectors, the human review task queue and the ARender relay.

KeyEnv variableDefaultDescription
file-connector.filesystem.rootFILECONNECTOR_FILESYSTEM_ROOT(unset — connector off)Root folder of the filesystem file connector. Files live under <root>/<tenant>/. Absolute paths, .., hidden segments, disallowed extensions and symbolic links that leave the root are refused. The application fails to start if the root is not a folder, or is not readable and writable by the application user. Without it, persist: true is refused with 422 FILE_STORAGE_UNAVAILABLE.
file-connector.filesystem.allowed-extensionsFILECONNECTOR_FILESYSTEM_ALLOWEDEXTENSIONSpdf,png,jpg,jpeg,tif,tiffExtensions the filesystem connector accepts (comma-separated).
task.reservation-seconds—900How long a reservation on a review task lasts.
task.max-payload-bytes—262144Largest task payload (413 beyond).
rendition.base-urlRENDITION_BASE_URL(unset)ARender base URL. uxopian-ai relays it at <app>/rendition/ behind the same gateway authentication, so the review screen needs no direct browser access to ARender.
agent.execution.reservation-millis—60000Lease a runner holds on a plan execution before another may take it over.

With Helm, set fileConnector.filesystem.existingClaim (a PersistentVolumeClaim), mountPath (default /data/documents) and allowedExtensions: the chart mounts the claim and sets the two environment variables. Without a claim nothing is mounted and persist stays disabled.

code-sandbox​

Code modules run JavaScript in a separate uxopian-code-sandbox service. The feature is opt-in: with no code-sandbox.url, the sandbox is off and no code tool is offered. The domains a module may reach are configured on the sandbox side (code-sandbox.network.allowed-domains there), not per module.

KeyEnv variableDefaultDescription
code-sandbox.urlCODESANDBOX_URL(unset — sandbox off)Base URL of uxopian-code-sandbox.
code-sandbox.secretCODESANDBOX_SECRET(unset)Shared secret used to call the sandbox.
code-sandbox.caller-nameCODESANDBOX_CALLERNAMEuxopian-aiCaller name presented to the sandbox.
code-sandbox.capability-profileCODESANDBOX_CAPABILITYPROFILEuxoaiSandbox capability profile the code runs with.
code-sandbox.max-active-sessionsCODESANDBOX_MAXACTIVESESSIONS16Executions allowed at once; one more fails immediately, asking to try again later.

The environment variable names follow Spring's relaxed binding of the property names; the shipped application.yml does not declare them.

alfresco​

Configuration for the Alfresco plugin. Since 2026.0.0-ft5, its tools are always registered when the JAR is present in plugins/; whether they're exposed to a given caller is controlled by that caller's usage profile tool/tag whitelist, not by plugins.tools.enabled-tags.

KeyEnv variableDefaultDescription
alfresco.base-urlALFRESCO_BASE_URL(empty)Alfresco REST API v1 base URL. Required when the plugin is enabled.
alfresco.legacy-base-urlALFRESCO_LEGACY_BASE_URL(auto-derived)Base URL for Alfresco legacy Web Script endpoints (/alfresco/s/…). Auto-derived from base-url when not set: if base-url contains /alfresco-api, it is replaced with /alfresco; if base-url ends with /api, the suffix becomes /s; otherwise /s is appended. Override only if the auto-derivation does not match your deployment layout.
alfresco.cmm-enabledALFRESCO_CMM_ENABLEDfalseEnable Alfresco Custom Content Model lookup. When disabled, the LLM sees only the fallback cm:* system properties.
alfresco.common-system-properties—cm:name, cm:title, cm:description, cm:created, cm:modified, cm:creator, cm:modifierList of system properties (name, label, description, indexable, allowed values) surfaced to the LLM when CMM is disabled. Override if your tenant uses a different default schema.

Example:

alfresco:
base-url: ${ALFRESCO_BASE_URL:}
# legacy-base-url is auto-derived from base-url — set only if the derivation is wrong
# legacy-base-url: ${ALFRESCO_LEGACY_BASE_URL:}
cmm-enabled: ${ALFRESCO_CMM_ENABLED:false}
# common-system-properties: (defaults shipped with the plugin)

See Integrate with Alfresco for deployment steps.

filenet​

Configuration for the FileNet plugin. Since 2026.0.0-ft5, its tools are always registered when the JAR is present in plugins/; whether they're exposed to a given caller is controlled by that caller's usage profile tool/tag whitelist, not by plugins.tools.enabled-tags.

There is no object store setting: the object store is the tenant, resolved per request by the ICN plugin and carried in its JWT — see How the tenant is resolved.

KeyEnv variableDefaultDescription
filenet.ce-api-url—(empty)Content Engine Web Services (CEWS) endpoint, e.g. http://<ce-host>:<port>/wsi/FNCEWS40MTOM/. Required when the plugin is enabled.
filenet.oidc-realmFILENET_OIDC_REALM(empty)Name of the OIDC/OAuth provider trust registered on the Content Platform Engine via ACCE. Every CE call is authenticated as the current caller (via OpenTokenCredentials), not a shared service account — see Integrate with FileNet. Required.
filenet.common-system-properties—DocumentTitle, DateCreated, DateLastModified, Creator, LastModifier, MajorVersionNumber, MimeTypeList of properties (name, title, dataType, multiValued, allowedValues) surfaced to the LLM as the searchable/readable data model. Override if your object store uses a different default schema.
filenet.writable-properties—(empty)List of properties (same structure as above) intended to be writable by the LLM. Configured but not yet wired to a callable tool — there is currently no LLM-callable way to update a FileNet document property.

Example:

filenet:
ce-api-url: ${FILENET_CE_API_URL:}
oidc-realm: ${FILENET_OIDC_REALM:}
# common-system-properties: (defaults shipped with the plugin)
# writable-properties:
# - name: DocumentTitle
# title: Document Title
# dataType: "xs:string"
# multiValued: false

The IBM Content Engine Java API dependencies (com.filenet:jace, com.filenet:p8cel10n) required to build this plugin are proprietary and resolved from the Arondor Artifactory, not Maven Central.

See Integrate with FileNet for deployment steps, including the ICN plugin and the gateway's FileNetProvider JWT settings.

mcp-server.yml​

MCP (Model Context Protocol) boot-time configuration. Starting with 2026.0.0-ft3, MCP connections are typically managed through the admin UI (Managing MCP servers) rather than this file; the shipped mcp-server.yml is commented out.

# mcp:
# client:
# name: uxopian-ai-mcp-server
# log-requests: true
# sse:
# url: ${MCP_SSE_URL:http://localhost:8081/uxopian/ai/sse}
KeyEnv variableDescription
mcp.sse.urlMCP_SSE_URLLegacy boot-time MCP SSE endpoint URL. Prefer the admin UI for runtime management.
mcp.client.name—MCP client name presented to the server.

script-scan.yml​

Configuration for the LLM-based security scan applied to admin-managed scripts (see Managing scripts). Added in 2026.0.0-ft4. The file is imported optionally, so its absence is non-fatal; without a configured provider, scripts can still be created, edited, and force-published, but the Scan & publish action is unavailable.

KeyEnv variableDefaultDescription
script.scan.llm-provider-idSCRIPT_SCAN_LLM_PROVIDER(empty)ID of a configured LLM provider used to run the scan. Required to enable scanning.
script.scan.llm-modelSCRIPT_SCAN_LLM_MODEL(empty)Model used for the scan; falls back to the provider's default model when blank.
script.scan.prompt—(built-in)The security-review prompt sent to the model. Override to customize the scan policy.

Example:

script:
scan:
llm-provider-id: ${SCRIPT_SCAN_LLM_PROVIDER:}
llm-model: ${SCRIPT_SCAN_LLM_MODEL:}
# prompt: (built-in security-review prompt; override to customize)

gateway-application.yaml​

Gateway (uxopian-gateway) configuration.

KeyDescription
server.portGateway listening port (default: 8085)
app.gateway.provider-headerHeader carrying the provider ID for multi-provider setups
app.routes[].idRoute identifier (used in logs)
app.routes[].uriBackend service URI (e.g., http://uxopian-ai:8080)
app.routes[].pathAnt path pattern — incoming requests must match this to activate the route
app.routes[].prefixBase prefix prepended to all security rule paths for matching against incoming requests
app.routes[].rewritePathComma-separated regex, replacement — rewrites the request path before forwarding to the backend. Uses Java named capture groups ((?<name>...)), referenced as $\{name} in the replacement.
app.routes[].providerAuthProvider bean name — either a built-in singleton (DevProvider, FlowerDocsProvider, Fast2Provider, AlfrescoProvider, FileNetProvider) or a name declared under app.providers below
app.routes[].security[].pathPath pattern for security rule (relative — combined with prefix at startup)
app.routes[].security[].publicIf true, no authentication required for this path
app.routes[].security[].rolesList of required roles for this path

YAML anchors (&ANCHOR / *alias) can be used to share URI and security rule definitions across multiple routes. Define anchors at the root level (before app:).

See Configure gateway routes for a step-by-step guide to deriving path, prefix, and rewritePath values, debug logging instructions, and a full FlowerDocs example.

The gateway's own endpoints (app.security)​

app.routes[].security[] rules only apply within their own route's path — they never cover paths the gateway serves itself (/actuator/**, and nothing else, since routes are the only other traffic). A top-level app.security list configures those gateway-owned paths:

KeyDescription
app.security[].pathPath pattern, matched as-is (no route prefix involved)
app.security[].publicIf true, no authentication required
app.security[].rolesList of required roles

Without this, /actuator/health falls through to "authenticated" by default — which 401s the Kubernetes liveness/readiness probe and crash-loops the pod. The shipped application.yml sets:

app:
security:
- path: "/actuator/health"
public: true
- path: "/actuator/**"
roles: ["ADMIN"]

Named provider instances (app.providers)​

Since 2026.0.0-ft5, a provider type that ships an AuthProviderFactory (currently Fast2Provider, AlfrescoProvider, and FileNetProvider) can be instantiated more than once, under an operator-chosen name — for example, to serve two separate FileNet tenants from one gateway. Omitting app.providers entirely keeps the previous single-instance-per-type behavior; this is purely additive.

KeyDescription
app.providers.<name>.typeOne of the provider types above that supports named instances
app.providers.<name>.config.*Arbitrary key/value configuration passed to that provider type's factory (same keys as the type's own dedicated config block)

Config keys mirror each provider's own dedicated block, kebab-cased: public-key / issuer / tenant-id / clock-skew-seconds for FileNetProvider, share-url / tenant-id / cache-ttl-minutes for AlfrescoProvider, public-key-url / tenant-id for Fast2Provider. These are the gateway's JWT-validation settings — not to be confused with uxopian-ai's own FileNet connector settings (filenet.ce-api-url, filenet.oidc-realm, configured on the ai-standalone side, see Integrate with FileNet).

app:
providers:
filenet-tenant-a:
type: FileNetProvider
config:
public-key: /path/to/tenant-a-icn-plugin-public-key.pem
issuer: icn-plugin
tenant-id: tenant-a-fallback
filenet-tenant-b:
type: FileNetProvider
config:
public-key: /path/to/tenant-b-icn-plugin-public-key.pem
issuer: icn-plugin
tenant-id: tenant-b-fallback
routes:
- id: filenet-a
provider: filenet-tenant-a
# ...
- id: filenet-b
provider: filenet-tenant-b
# ...

The instance name must not collide with a built-in provider bean name. Failing to declare type, referencing a type with no AuthProviderFactory, or a factory error at startup all fail fast with a clear message.

CORS (app.cors)​

Since 2026.0.0-ft5, cross-origin access is controlled by the gateway itself.

KeyDescription
app.cors.allowed-originsList of allowed origins for cross-origin requests. Empty (the default) allows none — set this explicitly if a browser client on a different origin must reach the gateway.

Gateway-signed internal auth (internal-auth.jwt)​

Since 2026.0.0-ft5, the gateway can sign every proxied request so uxopian-ai no longer has to trust bare X-User-* headers from whatever reaches it — see uxopian-ai's internal-auth.jwt.secret, which must match exactly.

KeyEnv variableDefaultDescription
internal-auth.jwt.secretINTERNAL_AUTH_JWT_SECRET(empty, signing off)HS256 shared secret, at least 32 bytes. Signing is simply inactive when unset — no error. Since 2026.0.0 uxopian-ai will not start without its own copy of this secret, so set it here too, with the same value.
internal-auth.jwt.issuerINTERNAL_AUTH_JWT_ISSUERuxopian-gateway-internaliss claim stamped on the issued assertion.
internal-auth.jwt.ttl-secondsINTERNAL_AUTH_JWT_TTL_SECONDS30Assertion lifetime.

Public paths get signed too, not just authenticated ones: any request the gateway forwards for a path marked public in app.security/app.routes[].security[] still carries a signed X-Gateway-Auth assertion when a secret is configured — an anonymous one (no sub/tenantId, just the provider claim). Any X-Gateway-Auth the client itself supplied is stripped and replaced first, never appended to.