Setting Up the AI Service

The AI Service is the core component of Robi AI. It handles chat and analysis requests from the Universal Controller, communicates with the AI MCP Server to execute actions, and queries the vector database for documentation context.

It is assumed you have already configured multiple Tomcat deployments and have a dedicated Tomcat instance ready for the AI Service (for example, at tomcat/instances/ai).

Installation Procedure

Deploy the WAR file

Copy the provided ai-{release}-{build}.war file into the webapps folder of your AI Service Tomcat instance, as ai.war.

Configure base settings

Create a configuration file for the AI Service. You can configure the service using either a setenv.bat / setenv.sh file in the instance's bin folder (environment variables), or an application.yml file placed in the instance's conf folder.

A sample application.yml is given below. This file gives the minimal configurations needed to start the AI Service.

Minimal configuration

application.yaml
spring:
  datasource-vectorstore-pgvector:
    url: ${DATASOURCE_VECTORSTORE_PGVECTOR_URL:jdbc:postgresql://localhost:5432/ai_db}
    username: ${DATASOURCE_VECTORSTORE_PGVECTOR_USER:postgres}
    password: ${DATASOURCE_VECTORSTORE_PGVECTOR_PASSWORD}
  ai:
    chat:
      provider: ${CHAT_PROVIDER:azure_openai}
    embedding:
      provider: ${EMBEDDING_PROVIDER:azure_openai}
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}
        # HTTP log detail level for Azure SDK requests. Valid values: NONE, BASIC, HEADERS, BODY_AND_HEADERS
        http-log-detail-level: ${AZURE_HTTP_LOG_DETAIL_LEVEL:BASIC}
        chat:
          options:
            deployment-name: ${AZURE_OPENAI_CHAT_DEPLOYMENT_NAME:gpt-4.1}
        embedding:
          options:
            deployment-name: ${AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME:text-embedding-3-small}
    mcp:
      client:
        streamable-http:
          connections:
            ai-mcp:
              url: ${MCP_SERVER_URL:http://localhost:8082/ai-mcp}
    vectorstore:
      provider: ${VECTORSTORE_PROVIDER:pgvector}
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: ${PGVECTOR_DIMENSIONS:1536}
        initialize-schema: true
        schema-name: public
        table-name: ${PGVECTOR_TABLE_NAME:vector_store}

logging:
  file:
    name: "${LOG_FILE_NAME:${LOG_DIR}/ai.log}"
  threshold:
    console: "${LOG_THRESHOLD_CONSOLE:OFF}"
  level:
    com.stonebranch.ai: ${LOGGING_LEVEL_COM_STONEBRANCH_AI:INFO}
    org.springframework: ${LOGGING_LEVEL_SPRING:INFO}
    org.springframework.ai: ${LOGGING_LEVEL_SPRING_AI:${LOGGING_LEVEL_SPRING:INFO}}
    getChatCompletionsSync: ${LOGGING_LEVEL_AZURE_HTTP:INFO}
    getEmbeddingsSync: ${LOGGING_LEVEL_AZURE_HTTP:INFO}
  logback:
    rollingpolicy:
      max-file-size: 10MB
      max-history: 7
      total-size-cap: 0B
      clean-history-on-start: true

stonebranch:
  ai:
    # API Key Authentication Configuration
    #
    # Each application represents a registered external service authenticating
    # against this instance. Each application defines one or more environments,
    # each with its own keys.
    # Keys can be a single value or a comma-separated list to support
    # key rotation without downtime.
    authentication:
      api-key:
        # Enable or disable API key authentication globally (default: false)
        enabled: ${API_KEY_AUTH_ENABLED:false}
        applications:
          uc:
            environments:
              # For UC instances that don't need environment-specific keys
              default:
                keys: ${UC_API_KEYS:}
              # Production
              prod:
                keys: ${UC_PROD_API_KEYS:}
              # Staging
              staging:
                keys: ${UC_STAGING_API_KEYS:}
              # Development
              dev:
                keys: ${UC_DEV_API_KEYS:}
              # QA/Testing
              qa:
                keys: ${UC_QA_API_KEYS:}
              # Disaster Recovery
              dr:
                keys: ${UC_DR_API_KEYS:}
              # Training
              training:
                keys: ${UC_TRAINING_API_KEYS:}
              # Demo
              demo:
                keys: ${UC_DEMO_API_KEYS:}

    # Property Encryption
    #
    # Encrypts sensitive properties (API keys, DB passwords) at rest in application.yml
    # using AES/GCM with a Key Encryption Key (KEK) from a keyring.
    #
    # On first start, plaintext sensitive values are automatically encrypted to ENC(...)
    # format. On every start, ENC(...) values are decrypted transparently.
    #
    # If neither property is set, encryption is disabled and the service runs normally.
    #
    # Two options for providing the keyring (use one, not both):
    #   file   — Path to keyring.json on the filesystem
    #   base64 — The keyring.json content, base64-encoded, passed as an environment
    #            variable. Useful for containers and Kubernetes secrets where mounting
    #            files is impractical.
    #            Generate with: cat keyring.json | base64 -w0
    keyring:
      file: ${KEYRING_FILE:}
      base64: ${KEYRING_BASE64:}

info

We recommend using these values (except for the options in the table below), unless you have a specific reason to change them. See Configuration for a full list of available options.

Set the following options with your own values:

Environment Variable / Property	Description
DATASOURCE_VECTORSTORE_PGVECTOR_URL `spring.datasource-vector-pgvector.url`	JDBC URL for your PGVector database
DATASOURCE_VECTORSTORE_PGVECTOR_USER `spring.datasource-vector-pgvector.username`	Database username
DATASOURCE_VECTORSTORE_PGVECTOR_PASSWORD `spring.datasource-vector-pgvector.password`	Database password
AZURE_OPENAI_API_KEY `spring.ai.azure.openai.api-key`	Your Azure OpenAI API key
AZURE_OPENAI_ENDPOINT `spring.ai.azure.openai.endpoint`	Your Azure OpenAI endpoint URL
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME `spring.ai.azure.openai.chat.options.deployment-name`	The name of your chat deployment
`AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` spring.ai.azure.openai.embedding.options.deployment-name`	The name of your embedding deployment
MCP_SERVER_URL `spring.ai.mcp.client.streamable-http.connetions.ai-mcp.url`	URL of the AI MCP Server (default: `http://localhost:8082/ai-mcp`)

Enable authentication

The AI Service uses an API key to validate that requests come from an authorized Universal Controller instance. When enabled, the Controller must be configured with a matching API key in AI Settings. Without it, requests to the AI Service will be rejected.

Authentication is disabled in the minimal configuration above to simplify initial setup. We strongly recommend enabling it before deploying to a production environment.

To enable authentication, set API_KEY_AUTH_ENABLED=true (or update the value in application.yml), then configure at least one key for your UC instance.

Configuring API Keys

API keys are configured per environment using environment variables. The minimal configuration already includes a set of pre-configured environments for common deployment scenarios:

Environment	Environment Variable	Intended Use
`default`	`UC_API_KEYS`	Single UC instance or simple deployments
`prod`	`UC_PROD_API_KEYS`	Production
`staging`	`UC_STAGING_API_KEYS`	Staging
`dev`	`UC_DEV_API_KEYS`	Development
`qa`	`UC_QA_API_KEYS`	QA / Testing
`dr`	`UC_DR_API_KEYS`	Disaster Recovery
`training`	`UC_TRAINING_API_KEYS`	Training
`demo`	`UC_DEMO_API_KEYS`	Demo

Environments are only active when their corresponding environment variable is set. You can use the default environment for simple single-instance deployments, or use named environments to manage multiple UC instances separately. We recommend using a different key for each environment.

You can also add custom environments beyond those listed above by extending the stonebranch.ai.authentication.api-key.applications.uc.environments block in application.yml:

uc:
  environments:
    my-custom-env:
      keys: ${UC_MY_CUSTOM_ENV_API_KEYS:}

Key Rotation

Each environment accepts a comma-separated list of keys, which allows you to rotate keys without downtime:

Add the new key alongside the old one: UC_API_KEYS="old-key,new-key"
Update the API Key in AI Settings to the new key
Once all UC instances are updated, remove the old key: UC_API_KEYS="new-key"

Security Recommendations

Keys should have sufficient entropy to be secure. We recommend at least 32 bytes (256 bits), generated using a cryptographically secure method. The following commands generate a suitable key:

# OpenSSL (recommended)
openssl rand -base64 32

# Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

We recommend rotating keys regularly. Your organization may have its own key requirements. Consult your security policy for specific guidance.

Startup Log

When the service starts, it logs the current authentication state. Verify the output matches your expected configuration:

Authentication enabled with keys configured:

===========================================
API Key Authentication Enabled
  uc/default: 1 key(s)
  uc/prod: 2 key(s)
Total API Keys: 3
===========================================

Authentication enabled but no keys set (error - all requests will be rejected):

===========================================
NO API KEYS CONFIGURED!
Configure stonebranch.ai.authentication.api-key.applications in application.yml
Or set environment variables: UC_API_KEYS, UC_PROD_API_KEYS, UC_DEV_API_KEYS
===========================================

Authentication disabled:

===========================================
API key authentication is DISABLED
This is NOT recommended for production
===========================================

Enable property encryption

Optional but recommended.

Sensitive values in application.yml (such as passwords and API keys) can be encrypted at rest. When a keyring is configured, the AI Service automatically encrypts any plaintext sensitive values in application.yml on first startup. On all subsequent startups, encrypted values are decrypted transparently. No manual steps are required after the initial setup. Values that are already encrypted are skipped.

If no keyring is configured, this feature is fully disabled and the service runs normally with plaintext values.

Generating a Keyring

Use the Keyring Manager to generate a keyring file:

./keyring-manager.sh init --keyring /path/to/keyring.json --description "My AI Service"

This creates a keyring.json file at the specified path. Store this file securely. It contains the encryption key used to protect your sensitive configuration values.

warning

This file contains sensitive keys used by the application. Ensure it is readable only by the Tomcat service account.

To rotate the primary key, use the following command:

./keyring-manager.sh rotate --keyring /secure/path/keyring.json --description "My AI Service"

warning

Keyring Manager triggers an automatic backup of keyring.json prior to any modification events. These backup files contain plaintext key material. Securely store or delete them after confirming the new keyring is functional.

Configuring the Keyring

Point the AI Service to your keyring using one of the following options (configure one, not both):

Property	Environment Variable	Description
`stonebranch.ai.keyring.file`	`KEYRING_FILE`	Path to `keyring.json` on the filesystem
`stonebranch.ai.keyring.base64`	`KEYRING_BASE64`	Base64-encoded keyring JSON content

For a standard Tomcat deployment, placing keyring.json at ${catalina.base}/conf/keyring.json and setting KEYRING_FILE to that path is the recommended approach. If storing the file on disk is not practical (for example, in a containerized environment), use KEYRING_BASE64 instead:

# Linux/Mac
export KEYRING_BASE64=$(cat keyring.json | base64 -w0)

# Windows PowerShell
$env:KEYRING_BASE64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes("keyring.json"))

tip

Encrypted ENC(...) values can also be passed via environment variables. If you set an environment variable to an ENC(...) value, the AI Service will decrypt it transparently, the same way it handles encrypted values in application.yml. This is useful when secrets are managed externally but still need to be encrypted.

Start the AI Service

Start the Tomcat instance for the AI Service. On Windows, run startup.bat from the instance's bin folder. On Linux, run startup.sh.

Check the logs in the instance's logs folder to verify that the AI Service started successfully. A successful startup will show the WAR deployed and Spring Boot initialized without errors.

info

You can also verify the service is running by accessing the actuator info endpoint: http://localhost:8081/ai/actuator/info. A healthy response will return JSON with the application name and version.

Once the AI Service is running, proceed to Set Up the AI MCP Server.

Installation Procedure​

Deploy the WAR file​

Configure base settings​

Enable authentication​

Configuring API Keys​

Key Rotation​

Security Recommendations​

Startup Log​

Enable property encryption​

Generating a Keyring​

Configuring the Keyring​

Start the AI Service​