Configuration Reference

This page documents the Spring Boot property surface that exists in TramAI 0.6.0. Every key below is bound by a @ConfigurationProperties class in the release; nothing is aspirational.

The Spring binding lives in tramai-spring-core (framework-level keys), the provider adapter modules (tramai-spring-provider-openai, tramai-spring-provider-anthropic, tramai-spring-provider-ollama), the secret backends (tramai-spring-secrets-file, -vault, -aws), and the sovereign modules (tramai-spring-sovereign, tramai-spring-boot-starter-sovereign-*).

tramai.profile

Selects the runtime profile. This is the sole runtime selector.

• Matching is case-insensitive.
• Any other value fails at startup with Unsupported tramai.profile '<value>'. Supported values: standard, sovereign. There is never a silent fallback.
• Exactly one runtime authority is active; standard and sovereign never coexist.
• tramai.sovereign.enabled: false is rejected at startup. The compatibility switch is retained but can only be true (or absent); select the standard runtime with tramai.profile: standard instead.

tramai:
  profile: sovereign

Standard Runtime Keys

Bound by TramaiProperties (@ConfigurationProperties("tramai")):

Provider names in models and in fallback routes must match registered provider names. A fallback route for a model requires an explicit primary route for that model; a duplicate primary route for the same model is a configuration error, not a silent replacement.

Provider Properties

Each Spring provider adapter binds its own namespace and registers a provider under the matching name.

OpenAI (tramai-spring-provider-openai)

tramai:
  providers:
    openai:
      api-key-secret-ref: env:OPENAI_API_KEY
      base-url: https://api.openai.com/v1

OpenAI-compatible (tramai-spring-provider-openai)

Binds tramai.providers.openai-compatible.* with the same fields as OpenAI plus provider-name (default openai-compatible), and registers the provider under that name. base-url is required here — without it the adapter produces no provider. The same applies to tramai.providers.ollama.base-url.

tramai:
  providers:
    openai-compatible:
      provider-name: compatible
      bearer-token-secret-ref: env:COMPATIBLE_API_TOKEN
      base-url: https://compatible.example.com/v1

Anthropic (tramai-spring-provider-anthropic)

tramai.providers.anthropic.api-key, .api-key-secret-ref, .base-url (default https://api.anthropic.com).

Ollama (tramai-spring-provider-ollama)

tramai.providers.ollama.base-url. The base URL is required for the adapter to produce a provider — without it, startup fails under sovereign validation with no provider available.

tramai:
  providers:
    ollama:
      base-url: http://localhost:11434

Gemini, Bedrock, Azure OpenAI, and DeepSeek ship as standalone adapters. Register them as ModelProvider beans in Spring; there is no property namespace for them in 0.6.0. See Providers.

Secrets

Reference schemes resolved by the bundled resolvers:

A field cannot be configured with a direct value and its *-secret-ref at the same time — that combination fails fast, as does a reference no resolver can resolve.

Complete Standard Example

tramai:
  profile: standard

  default-provider: openai
  models:
    gpt-4o: openai
    gpt-4o-mini: openai
    claude-sonnet-4-20250514: anthropic
    llama3.2: ollama
  fallbacks:
    gpt-4o:
      - provider: openai
        model: gpt-4o-mini
      - provider: ollama
        model: llama3.2

  resilience:
    circuit-breaker:
      enabled: true
      failure-threshold: 3
      open-duration-millis: 30000
    retry:
      max-retry-after-millis: 20000
      jitter-ratio: 0.1

  cost:
    token-budget:
      hard-max-tokens-per-attempt: 4000
      hard-max-tokens-per-operation: 12000
      soft-max-tokens-per-operation: 8000

  cache:
    in-memory:
      enabled: true
      max-entries: 1000

  security:
    classification:
      enabled: false
      default-classification: INTERNAL
      max-text-length: 100000
    model-registry:
      enabled: false

  secrets:
    file:
      allowed-directory: /etc/tramai/secrets
    vault:
      enabled: false
      base-url: https://vault.example.com
      token-secret-ref: env:VAULT_TOKEN
      mount-path: secret
      kv-version: 2
      default-field: value
    aws-secrets-manager:
      enabled: false
      region: eu-west-1
      access-key-id-secret-ref: env:AWS_ACCESS_KEY_ID
      secret-access-key-secret-ref: env:AWS_SECRET_ACCESS_KEY
      default-field: value

  providers:
    openai:
      api-key-secret-ref: env:OPENAI_API_KEY
      base-url: https://api.openai.com/v1
    openai-compatible:
      provider-name: compatible
      bearer-token-secret-ref: env:COMPATIBLE_API_TOKEN
      base-url: https://compatible.example.com/v1
    anthropic:
      api-key-secret-ref: env:ANTHROPIC_API_KEY
      base-url: https://api.anthropic.com
    ollama:
      base-url: http://localhost:11434

Sovereign Runtime

The sovereign runtime is selected with tramai.profile: sovereign and configured under tramai.sovereign.*. The allowlists are mandatory: missing allowed models, missing allowed providers, a provider without a trust zone, a model without a route, or a route that points at a non-allowed provider all fail startup.

tramai:
  profile: sovereign

  providers:
    ollama:
      base-url: http://localhost:11434

  sovereign:
    allowed-models:
      - llama3.2
    allowed-providers:
      - ollama
    allowed-tools:
      - schedule-payment
    allowed-permissions:
      - payment.schedule
    provider-zones:
      ollama: LOCAL
    models:
      llama3.2: ollama

Sovereign Persistence

tramai-spring-boot-starter-sovereign-persistence-file and -jdbc bind the same prefix:

tramai:
  sovereign:
    persistence:
      type: file
      base-dir: ./data/tramai-sovereign
      encryption:
        key-env: TRAMAI_SOVEREIGN_STORE_KEY

Sovereign Ops

Bound by tramai-spring-boot-starter-sovereign-ops (the worker-status endpoint property is owned by tramai-spring-boot-starter-sovereign-ops-actuator):

tramai:
  sovereign:
    ops:
      outbox:
        worker:
          enabled: true
          lease-enabled: true
      approved-resume-worker:
        enabled: true

What Is Not Configurable In 0.6.0

These do not exist as properties, in either profile:

• provider-level timeout or retry-policy configuration — timeouts and retries are per operation via @Operation(timeoutMillis = ..., providerRetries = ...)
• framework-level default max tokens or temperature
• streaming configuration — streaming is inferred from the return type
• preflight token estimation before a provider call is sent

Related Pages

• Standalone Builder
• Providers
• Spring Boot Integration
• Production Hardening