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.

Key	Env variable	Default	Description
`app.base-url`	`APP_BASE_URL`	(empty)	Public base URL for the application (used in generated links)
`server.port`	`UXOPIAN_AI_PORT`	`8080`	HTTP port uxopian-ai listens on
`server.servlet.context-path`	`CONTEXT_PATH`	(empty)	Optional servlet context path prefix
`tools.enabled`	`TOOLS_ENABLED`	`true`	Set to `false` to disable all tool execution
`plugins.root.path`	`PLUGINS_ROOT_PATH`	`plugins/`	Directory scanned at startup for plugin JARs
`plugins.tools.enabled-tags`	`PLUGINS_TOOLS_ENABLED_TAGS`	`flowerdocs,files`	Comma-separated whitelist of `@ToolService` tag values registered at startup (see Plugin system). Empty list = all tools registered.
`spring.profiles.active`	`SPRING_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}

opensearch.yml

OpenSearch connection settings.

Key	Env variable	Default	Description
`opensearch.host`	`OPENSEARCH_HOST`	`localhost`	OpenSearch host
`opensearch.port`	`OPENSEARCH_PORT`	`9200`	OpenSearch port
`opensearch.scheme`	`OPENSEARCH_SCHEME`	`http`	Connection scheme (`http` or `https`)
`opensearch.username`	`OPENSEARCH_USERNAME`	(empty)	Username for authenticated OpenSearch
`opensearch.password`	`OPENSEARCH_PASSWORD`	(empty)	Password for authenticated OpenSearch
`opensearch.force-refresh-index`	`OPENSEARCH_FORCE_REFRESH_INDEX`	`false`	Force index refresh after each write (slow; for testing only)
`opensearch.index-prefix`	`OPENSEARCH_INDEX_PREFIX`	`uxopian-ai`	Prefix 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:}
  force-refresh-index: ${OPENSEARCH_FORCE_REFRESH_INDEX:false}

llm-clients-config.yml

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

Default LLM settings

Key	Env variable	Default	Description
`llm.default.provider`	`LLM_DEFAULT_PROVIDER`	`openai`	Default LLM provider identifier
`llm.default.model`	`LLM_DEFAULT_MODEL`	`gpt-5.1`	Default model name
`llm.default.base-prompt`	`LLM_DEFAULT_PROMPT`	`basePrompt`	Default base prompt ID
`llm.context`	`LLM_CONTEXT_SIZE`	`10`	Number of previous requests included in each LLM call
`llm.debug.enabled`	`LLM_DEBUG`	`false`	Enable verbose LLM request/response logging

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

Provider	Extra keys	Description
`bedrock`	`AwsRegion`, `AwsAccessKey`, `AwsSessionToken`	AWS credentials and region
`nu-extract`	`modelId`	Model ID override (defaults to `modelName` if absent)

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

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.

Key	Description
`prompts.backup.path`	Directory for prompt backups. Env: `PROMPTS_BACKUP_PATH`. Default: `./prompts/`
`prompts.globals`	List of global prompt definitions (see structure below)
`prompts.tenants`	List of per-tenant prompt overrides

Prompt definition structure

- id: <unique-id>
  role: SYSTEM | USER | ASSISTANT
  content: |
    Thymeleaf template content...
    [[${variable}]]
  requiresMultiModalModel: false
  requiresFunctionCallingModel: false
  reasoningDisabled: false
  defaultLlmProvider: ""       # optional: override provider for this prompt
  defaultLlmModel: ""          # optional: override model for this prompt

Tenant override structure

prompts:
  tenants:
    - tenantId: <tenant-id>
      mergeStrategy: merge | replace
      prompts:
        - id: <prompt-id>
          role: USER
          content: |
            Override content...

goals.yml

Goal group definitions.

Key	Description
`goals.backup.path`	Directory for goal backups. Env: `GOALS_BACKUP_PATH`. Default: `./goals/`
`goals.globals`	List of global goal groups
`goals.tenants`	List of per-tenant goal group overrides

Goal group structure

goals:
  globals:
    - id: <group-id>
      goals:
        - promptId: <prompt-id>
          filter: "true"          # Thymeleaf boolean expression
          index: 1                # Execution order (ascending)

Tenant override structure

goals:
  tenants:
    - tenantId: <tenant-id>
      mergeStrategy: merge | replace
      goalGroups:
        - id: <group-id>
          goals:
            - promptId: <prompt-id>
              filter: "[[${documentType == 'contract'}]]"
              index: 10

metrics.yml

Micrometer metrics and actuator configuration.

Key	Description
`management.elastic.metrics.export.enabled`	Enable/disable OpenSearch metrics export (default: `true`)
`management.elastic.metrics.export.host`	OpenSearch URL for metrics. Default reads from `opensearch.*` properties.
`management.elastic.metrics.export.index`	Index name for metrics (default: `micrometer-metrics`)
`management.elastic.metrics.export.auto-create-index`	Auto-create metrics index (default: `true`)
`management.endpoints.web.exposure.include`	Exposed actuator endpoints. Default: `health,info,loggers`
`management.metrics.uxopian-ai.enable`	Enable 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.

Key	Env variable	Default	Description
`hazelcast.cluster-name`	—	`uxopian-ai-cluster`	Hazelcast cluster name
`hazelcast.kubernetes.enabled`	`HAZELCAST_KUBERNETES_ENABLED`	`false`	Enable Kubernetes service discovery
`hazelcast.kubernetes.service-dns`	`HAZELCAST_KUBERNETES_SERVICE_DNS`	`ai-standalone-headless`	Kubernetes headless service DNS name
`hazelcast.kubernetes.namespace`	`HAZELCAST_KUBERNETES_NAMESPACE`	`default`	Kubernetes namespace for discovery

alfresco

Configuration for the Alfresco plugin (loaded only when plugins.tools.enabled-tags contains alfresco).

Key	Env variable	Default	Description
`alfresco.base-url`	`ALFRESCO_BASE_URL`	(empty)	Alfresco REST API v1 base URL. Required when the plugin is enabled.
`alfresco.legacy-base-url`	`ALFRESCO_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-enabled`	`ALFRESCO_CMM_ENABLED`	`false`	Enable 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:modifier`	List 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.

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}

Key	Env variable	Description
`mcp.sse.url`	`MCP_SSE_URL`	Legacy boot-time MCP SSE endpoint URL. Prefer the admin UI for runtime management.
`mcp.client.name`	—	MCP client name presented to the server.

gateway-application.yaml

Gateway (uxopian-gateway) configuration.

Key	Description
`server.port`	Gateway listening port (default: `8085`)
`app.gateway.provider-header`	Header carrying the provider ID for multi-provider setups
`app.routes[].id`	Route identifier (used in logs)
`app.routes[].uri`	Backend service URI (e.g., `http://uxopian-ai:8080`)
`app.routes[].path`	Ant path pattern — incoming requests must match this to activate the route
`app.routes[].prefix`	Base prefix prepended to all security rule paths for matching against incoming requests
`app.routes[].rewritePath`	Comma-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[].provider`	AuthProvider bean name (e.g., `DevProvider`, `FlowerDocsProvider`, `Fast2Provider`)
`app.routes[].security[].path`	Path pattern for security rule (relative — combined with `prefix` at startup)
`app.routes[].security[].public`	If `true`, no authentication required for this path
`app.routes[].security[].roles`	List 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.

application.yml​

opensearch.yml​

llm-clients-config.yml​

Default LLM settings​

Provider configuration structure​

Supported provider identifiers​

Provider-specific extras​

Tenant overrides​

prompts.yml​

Prompt definition structure​

Tenant override structure​

goals.yml​

Goal group structure​

Tenant override structure​

metrics.yml​

hazelcast.yml​

alfresco​

mcp-server.yml​

gateway-application.yaml​

Related pages​

application.yml

opensearch.yml

llm-clients-config.yml

Default LLM settings

Provider configuration structure

Supported provider identifiers

Provider-specific extras

Tenant overrides

prompts.yml

Prompt definition structure

Tenant override structure

goals.yml

Goal group structure

Tenant override structure

metrics.yml

hazelcast.yml

alfresco

mcp-server.yml

gateway-application.yaml

Related pages