5. AI Assistant (XAssistant) Configuration

Starting with 2.14.0 the AI assistant is a separate Spring profile agent, and in the Enterprise Edition the LLM API keys entered by the admin are stored encrypted. Check the following before upgrading.

Turning the agent on or off

The Spring profile agent turns the assistant on. Without it, XOE starts normally, but the assistant and its configuration endpoints are not available.
The released xoe.jar is built with the Maven profile agent, so agent is part of the default spring.profiles.active in the jar.

Attention

If you set --spring.profiles.active=... on the command line (or SPRING_PROFILES_ACTIVE), you replace the default list and have to add agent yourself, e.g.:

java -jar xoe.jar --spring.profiles.active=agent ...

If you leave out agent, the assistant is turned off.

Encryption key for the API keys (Enterprise Edition, required with agent)

In the Enterprise Edition XOE with active agent profile does not start unless an encryption key is configured. The key must be an AES key of 256 bits.

Property	Environment variable	Required	Description
`xplain.agent.encryption.api-key.key-file.path`	`XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_PATH`	yes	Path to the key file
`xplain.agent.encryption.api-key.key-file.type`	`XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_TYPE`	yes	`raw` or `p12` (not case-sensitive)
`xplain.agent.encryption.api-key.key-file.p12.container-password`	`XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_P12_CONTAINER_PASSWORD`	for `p12`	Password of the PKCS12 keystore
`xplain.agent.encryption.api-key.key-file.p12.key-name`	`XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_P12_KEY_NAME`	no	Alias of the key; needed when the keystore holds more than one entry

Key file types:

raw: a text file with the 32 key bytes, Base64 encoded, e.g. made with
```
openssl rand -base64 32 > agent-api-key.key
```

p12: a PKCS12 keystore with an AES secret key, e.g. made with

keytool -genseckey -alias agent-api-key -keyalg AES -keysize 256 -storetype PKCS12 -keystore agent-api-key.p12

Example 1: raw key from an environment variable via a Docker secret

As used for the Synthea and NBA deployments. You don’t need a key file on the host: Docker Compose takes the Base64 key from the environment variable AGENT_API_KEY_ENCRYPTION_KEY_BASE64 and mounts it in the container as the file /run/secrets/agent_api_key_encryption_key_base64.

Make the key once and keep it safe (e.g. as a masked CI variable or in a secrets manager):
```
openssl rand -base64 32
```

Set it in the environment before starting the container:

export AGENT_API_KEY_ENCRYPTION_KEY_BASE64='<output of openssl rand -base64 32>'
docker compose up -d

docker-compose.yml:

services:
  xoe:
    environment:
      - XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_PATH=/run/secrets/agent_api_key_encryption_key_base64
      - XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_TYPE=raw
    secrets:
      - agent_api_key_encryption_key_base64

secrets:
  agent_api_key_encryption_key_base64:
    environment: AGENT_API_KEY_ENCRYPTION_KEY_BASE64

Always use the same key value: a new value makes the saved API keys unreadable.

Example 2: PKCS12 keystore (`p12`)

Make the keystore once and back it up. keytool asks for the keystore password; for PKCS12 the key itself uses the same password:

keytool -genseckey -alias agent-api-key -keyalg AES -keysize 256 -storetype PKCS12 -keystore agent-api-key.p12

Check that it holds the AES key:

keytool -list -keystore agent-api-key.p12 -storetype PKCS12

Start XOE directly with the keystore. Pass the password as an environment variable so it doesn’t show in the process list or shell history:

export XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_P12_CONTAINER_PASSWORD='<keystore password>'
java -jar xoe.jar \
  --xplain.agent.encryption.api-key.key-file.type=p12 \
  --xplain.agent.encryption.api-key.key-file.path=/opt/xoe/keys/agent-api-key.p12 \
  --xplain.agent.encryption.api-key.key-file.p12.key-name=agent-api-key

key-name is the -alias from step 1. You can leave it out if the keystore holds only this one key.

Docker variant: mount the keystore as a file secret and pass the password from the host environment:

services:
  xoe:
    environment:
      - XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_PATH=/run/secrets/agent_api_key_p12
      - XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_TYPE=p12
      - XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_P12_KEY_NAME=agent-api-key
      - XPLAIN_AGENT_ENCRYPTION_API_KEY_KEY_FILE_P12_CONTAINER_PASSWORD=${AGENT_API_KEY_P12_PASSWORD?AGENT_API_KEY_P12_PASSWORD missing}
    secrets:
      - agent_api_key_p12

secrets:
  agent_api_key_p12:
    file: ./agent-api-key.p12

export AGENT_API_KEY_P12_PASSWORD='<keystore password>'
docker compose up -d

Keep the keystore file and its password; without both, the saved API keys can’t be decrypted.

Notes

The LLM configuration is stored in <xplainPath>/global-ai-agent-config/ai-agent-config.json.
Keep the key file safe and back it up. The key ID is derived from the key itself: if the key is lost or replaced, the saved API keys can no longer be decrypted and the admin must enter them again.