Application properties
This appendix is the exhaustive property interface carried forward from the previous configuration reference. Use the task-oriented Operations guides for procedures, then use this page to confirm exact names and defaults for the chart version you are deploying.
With the Helm chart, place application YAML under the top-level config value. It is applied after the chart's base and generated configuration. A Helm upgrade that changes config updates the chart-managed ConfigMap and rolls the Koldan workloads. If configuration is supplied by another supported deployment system, roll every workload that consumes the changed property; do not assume properties are reloaded at runtime.
Defaults shown as blank or (empty) mean no value is supplied. A value in the form ${...} is inherited from the referenced property. A dash indicates that no concrete default is defined in this reference. A workload-specific default is stated explicitly where it differs between workloads.
Treat any password, API key, access key, client secret, HMAC secret, private-key path, or credential document as sensitive. Do not commit sensitive values to source control or expose them through command arguments, rendered manifests, logs, or support bundles. See Configuration and secrets.
Site properties
These settings change site identification and the update locations presented to supported clients.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.site.name | Site title/name displayed in UI | Koldan | Controls the main branding text shown throughout the application interface |
| koldan.site.updates-url-override | Overrides the update URL for desktop clients | (empty) | Defaults to /api/update on the HTTP server. Use this to customize where desktop clients check for updates |
| koldan.site.updates-url-v2-override | Overrides the update URL for desktop clients for V2 updater | (empty) | Defaults to /api/update/v2/updates.xml on the HTTP server |
Feature properties
Feature properties control optional capabilities that can be enabled or disabled for the site. Each feature requires both a valid license with the corresponding feature flag and the property to be enabled. Features are disabled by default and must be explicitly enabled in the configuration.
| Property | Description | Default | License Feature Required |
|---|---|---|---|
| koldan.features.session-history-enabled | Enables the session history feature. When enabled, speech session results (segments) are saved to S3 storage and can be retrieved later via the GetSessionHistoryResults API. When disabled, only session metadata records are saved but segment data is not stored or retrievable. |
false | session-history |
| koldan.features.session-history-summary-enabled | Enables AI-generated summaries for session history. When enabled, users can request summaries of their recorded speech sessions via the RequestNewSummary API. Requires session-history feature to also be enabled. |
false | session-history-summary |
| koldan.features.online-diarization-enabled | Enables online speaker diarization during speech recognition. When enabled, users can request diarization in gRPC recognition headers or WebSocket session.start.config.diarization to identify and tag different speakers in real-time. Sessions requesting diarization are rejected if disabled. |
false | online-diarization |
| koldan.features.session-history-autotitle-enabled | Enables automatic session titling after a session ends. Requires session-history to also be enabled. |
false | autotitle |
| koldan.features.ai-simple-text-summary-enabled | Makes the text-summary capability available when its provider configuration is valid. When disabled, requests are rejected. | false | - |
| koldan.features.speech-services-enabled | Makes the speech-services HTTP endpoints available. When disabled, those endpoints are unavailable. | false | speech-services |
| koldan.features.multi-tenancy-enabled | Honor the X-Tenant-Id request header. When disabled, requests use the default tenant even when the header is present. |
false | multi-tenancy |
S3 Object Storage
These properties select the S3-compatible endpoint and credentials used for Koldan object data. Provision and test the bucket before enabling dependent capabilities. See S3 object storage.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.s3.enabled | Enable use of the configured S3-compatible object store | true | |
| koldan.s3.url | S3 endpoint URL | http://localhost:9000 | |
| koldan.s3.bucket | Default S3 bucket name | koldan | |
| koldan.s3.access-key | S3 access key, required when enabled is true |
||
| koldan.s3.secret-key | S3 secret key, required when enabled is true |
Default tenant OIDC configuration
These properties provide the initial OIDC registration and service credentials used by the default tenant. Use endpoints from the provider's published metadata, keep client secrets in approved secret storage, and verify both browser and workload connectivity. See Identity providers.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.oidc.default-tenant.client-id | OAuth2 client ID for the default tenant's OIDC provider | Required for bootstrap | |
| koldan.oidc.default-tenant.client-secret | OAuth2 client secret for the default tenant's OIDC provider | Required for bootstrap | |
| koldan.oidc.default-tenant.issuer-uri | OIDC issuer URI | Required for bootstrap | |
| koldan.oidc.default-tenant.authorization-uri | OIDC authorization endpoint | ||
| koldan.oidc.default-tenant.token-uri | OIDC token endpoint | Required for bootstrap and engine token generation | |
| koldan.oidc.default-tenant.user-info-uri | OIDC user info endpoint | ||
| koldan.oidc.default-tenant.jwk-set-uri | OIDC JWK Set URI for token signature verification | Required for bootstrap | |
| koldan.oidc.default-tenant.end-session-uri | OIDC end session (logout) endpoint | ||
| koldan.oidc.default-tenant.engine.client-id | Engine OAuth2 client ID for service-to-service authentication | koldan-engine | Used by engines to obtain client-credentials tokens |
| koldan.oidc.default-tenant.engine.client-secret | Engine OAuth2 client secret | Required for engine token generation. Use env var KOLDAN_ENGINE_OIDC_CLIENT_SECRET |
Elasticsearch
These properties control the legacy Koldan Desktop client-log integration. Deployments that do not support Koldan Desktop can disable it; Koldan then creates no Elasticsearch client, omits the legacy HTTP log endpoints and gRPC remote-logging service, and excludes Elasticsearch from health.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.elasticsearch.enabled | Enable legacy desktop log storage and APIs | true | Set to false when Koldan Desktop is not used. |
| koldan.elasticsearch.mandatory | If true, health/readiness fails when ES is down | true (api modules), false (engines) | |
| koldan.elasticsearch.host | Elasticsearch server host | localhost | |
| koldan.elasticsearch.port | Elasticsearch server port | 9200 | |
| koldan.elasticsearch.index | Elasticsearch index name for client logs | koldan |
Engine services
These properties control the bind address, advertised endpoint, management endpoint, startup warm-up, and graceful shutdown behavior of enabled engine workloads.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.engine.hostname | Hostname advertised by the engine for workload-to-workload connections | localhost | |
| koldan.engine.port | Binding port for engine gRPC server | 8200 | |
| koldan.engine.management-port | Actuator management port | 5200 | |
| koldan.engine.preset-name | Preset name for engine runtime and model selection | (required) | |
| koldan.engine.model-temp-dir | Filesystem path to a local model directory. Engines may load models from here when S3 is disabled or as a cache. | (empty) | When empty, defaults to ${java.io.tmpdir} |
| koldan.engine.warmup.enabled | Whether to enable engine warmup on startup, recommended | true | |
| koldan.engine.warmup.timeout | Warmup timeout in seconds | 30 | |
| koldan.engine.warmup.noise-duration | Duration (in seconds) of synthetic noise added to the input audio during warmup | 10 | |
| koldan.engine.shutdown-timeout-seconds | Maximum time in seconds to wait for active recognitions to complete during graceful shutdown | 300 | |
| koldan.engine.k2.* | K2 Engine configurations | - | See K2 Config section |
gRPC API service
These properties control the gRPC bind and advertised endpoints, TLS, graceful shutdown, result filtering, optional diarization connectivity, and recording behavior. Keep the advertised endpoint aligned with the client-facing load balancer or Route. See Operational endpoints and TLS and custom CAs.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.api-grpc.address | Address registered for workload-to-workload gRPC connections | localhost | |
| koldan.api-grpc.port | TCP port for API gRPC server | 8195 | |
| koldan.api-grpc.management-port | Actuator management port | 5195 | |
| koldan.api-grpc.shutdown-timeout-seconds | Maximum time in seconds to wait for active requests to complete during graceful shutdown | 300 | |
| koldan.api-grpc.advertisement.address | gRPC server advertisement address | ${koldan.api-grpc.address} |
Use gRPC binding address by default |
| koldan.api-grpc.advertisement.port | gRPC server advertisement port | ${koldan.api-grpc.port} |
Use gRPC binding port by default |
| koldan.api-grpc.advertisement.ssl | Advertise that client-facing gRPC connections require TLS | ${koldan.api-grpc.ssl.enabled} |
Inherits the gRPC server TLS setting unless overridden |
| koldan.api-grpc.ssl.enabled | Whether to enable SSL on gRPC server | false | |
| koldan.api-grpc.ssl.use-spring-ssl-context | Use Spring-managed SSL context for gRPC server. When true, koldan.api-grpc.ssl.enabled is ignored. |
false | When true, you may need to set koldan.api-grpc.advertisement.ssl manually |
| koldan.api-grpc.ssl.key-store | Keystore path | - | |
| koldan.api-grpc.ssl.key-store-password | Keystore password | - | |
| koldan.api-grpc.ssl.key-store-type | Keystore type (usually PEM/PKCS12) | PKCS12 | |
| koldan.api-grpc.ssl.key-file | Private key file (PEM) when using PEM mode | - | |
| koldan.api-grpc.ssl.cert-file | Certificate file (PEM) when using PEM mode | - | |
| koldan.api-grpc.online.words-filter.enabled | Whether to filter configured insertions and disallowed words from online recognition results | true | |
| koldan.api-grpc.online.words-filter.words | Set of words (can be comma separated) to filter out from results | NOSE,NOS,SPN,SP | |
| koldan.api-grpc.online.diarization.uri | Target address of the diarization service ([scheme://][authority/]endpoint) |
localhost:7400 | Example values: localhost:7400, dns:///example.com:7400, static://addr1:7400,addr2:7400 |
| koldan.api-grpc.online.diarization.load-balancing-policy | Sets the load balancing policy for the connection (pick_first, round_robin) |
round_robin | |
| koldan.api-grpc.online.diarization.connection-timeout-ms | TCP connection timeout in milliseconds | 5000 | |
| koldan.api-grpc.online.diarization.keep-alive-time-ms | Keep-alive ping interval in milliseconds | 30000 | |
| koldan.api-grpc.online.diarization.keep-alive-timeout-ms | Keep-alive ping timeout in milliseconds | 5000 | |
| koldan.api-grpc.online.diarization.keep-alive-without-calls | Send keep-alive pings even when there are no active RPCs | false | |
| koldan.api-grpc.online.diarization.max-inbound-message-size | Maximum inbound message size accepted by the client channel (bytes) | 4194304 (4 MiB) | |
| koldan.api-grpc.online.diarization.ssl.enabled | Enable TLS for the client connection to the diarization server | false | |
| koldan.api-grpc.online.diarization.certificate-path | Path to client certificate file (PEM) used for mTLS | Required when ssl.enabled=true and server requires client cert | |
| koldan.api-grpc.online.diarization.private-key-path | Path to client private key file (PEM) used for mTLS | Required with certificate-path and server requires client cert | |
| koldan.api-grpc.online.diarization.trust-cert-collection-path | Path to trusted CA certificates file (PEM) to validate server certificate | ||
| koldan.api-grpc.recordings.enabled | Whether to enable audio recording (PCM) for speech recognition sessions. Recordings are stored in S3. | false | Requires session-history feature to be enabled for tracking. |
HTTP API service
These properties control the HTTP bind and advertised endpoints, update storage, allowed download sources, and cross-origin access. Keep the advertised endpoint aligned with the client-facing Ingress, Route, or gateway.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.api-http.port | Bind port for the API HTTP server | 8193 | |
| koldan.api-http.management-port | Actuator management port | 5193 | |
| koldan.api-http.advertisement.address | HTTP server advertisement address | ${koldan.api-grpc.address} |
|
| koldan.api-http.advertisement.port | HTTP server advertisement port | ${koldan.api-http.port} |
|
| koldan.api-http.advertisement.ssl | HTTP server advertise SSL for external connections | ${server.ssl.enabled} |
|
| koldan.api-http.security.model-url-whitelist-pattern | Regex pattern for whitelisting URL's for downloading models to Koldan | ^https:\/\/(www\.)?dixilang\.com(\/.*)?$ |
|
| koldan.api-http.updates-dir | Path to directory to serve updates from (static) | ./updates |
|
| koldan.api-http.cors.enabled | Whether to enable Cross-Origin Resource Sharing | false | For production the recommended value is false |
Rate Limits
These are fallback request limits when no more-specific runtime policy exists. Values are requests per minute unless stated otherwise. The effective order is user override, tenant default, then application property.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.api.rate-limits.file-uploads | Maximum file upload requests per minute | 20 | |
| koldan.api.rate-limits.transcription-job-executions | Maximum transcription job execution requests per minute | 20 | |
| koldan.api.rate-limits.summary-executions | Maximum summary execution requests per minute | 30 | |
| koldan.api.rate-limits.translation-executions | Maximum translation execution requests per minute | 30 | |
| koldan.api.rate-limits.text-translation-executions | Maximum text translation execution requests per minute | 60 | |
| koldan.api.rate-limits.global-requests | Maximum total API requests per minute (across all operations) | 600 | Applies to every authenticated request, all endpoints |
| koldan.api.rate-limits.speaker-enrollment-creations | Maximum speaker enrollment creation requests per minute | 10 | |
| koldan.api.rate-limits.speaker-verification-executions | Maximum speaker verification requests per minute | 60 | |
| koldan.api.rate-limits.speaker-voice-print-previews | Maximum voice-print quality preview requests per minute | 10 | |
| koldan.api.rate-limits.speaker-voice-print-creations | Maximum voice-print creation requests per minute | 10 | |
| koldan.api.rate-limits.speaker-voice-print-rebuild-starts | Maximum voice-print rebuild starts per 60 minutes | 1 | |
| koldan.api.rate-limits.speaker-recording-downloads | Maximum speaker recording downloads per minute | 30 |
Quotas
These values seed quotas for newly created tenants. Runtime tenant, subscription-plan, or user policy can override them.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.api.quotas.monthly-speaker-verifications | Monthly speaker verification requests | 10000 | |
| koldan.api.quotas.monthly-speaker-enrollments | Monthly speaker enrollment creation requests | 1000 | |
| koldan.api.quotas.monthly-speaker-voice-print-builds | Monthly voice-print build/rebuild starts | 100 | |
| koldan.api.quotas.speaker-biometric-storage-limit | Retained speaker biometric storage limit in bytes | 2147483648 | 2 GiB |
| koldan.api.quotas.max-speakers | Maximum active speakers per user | 10000 | |
| koldan.api.quotas.max-enrollments-per-speaker | Maximum active enrollments per speaker | 50 | |
| koldan.api.quotas.max-voice-prints-per-speaker | Maximum active voice prints per speaker | 20 |
Session History Post-Session Diarization
These properties control the optional diarization service used for completed session recordings. Enabling it adds a gRPC dependency; validate endpoint reachability, capacity, timeout, and TLS before enabling the feature.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.session-history-post-diarization.enabled | Whether post-session diarization is enabled | false | |
| koldan.session-history-post-diarization.min-duration-ms | Minimum audio duration (ms) to be eligible for post-diarization | 60000 | |
| koldan.session-history-post-diarization.uri | URI of the post-session diarization server (host:port) | localhost:7400 | Example values: localhost:7400, dns:///example.com:7400, static://addr1:7400,addr2:7400 |
| koldan.session-history-post-diarization.load-balancing-policy | Sets the load balancing policy for the connection | round_robin | pick_first, round_robin |
| koldan.session-history-post-diarization.connection-timeout-ms | TCP connection timeout in milliseconds | 5000 | |
| koldan.session-history-post-diarization.keep-alive-time-ms | Keep-alive ping interval in milliseconds | 30000 | |
| koldan.session-history-post-diarization.keep-alive-timeout-ms | Keep-alive ping timeout in milliseconds | 5000 | |
| koldan.session-history-post-diarization.keep-alive-without-calls | Send keep-alive pings even when there are no active RPCs | false | |
| koldan.session-history-post-diarization.max-inbound-message-size | Maximum inbound message size accepted by the client channel (bytes) | 4194304 (4 MiB) | |
| koldan.session-history-post-diarization.ssl-enabled | Enable TLS for the client connection to the diarization server | false | |
| koldan.session-history-post-diarization.certificate-path | Path to client certificate file (PEM) used for mTLS | Required when ssl-enabled=true and server requires client cert | |
| koldan.session-history-post-diarization.private-key-path | Path to client private key file (PEM) used for mTLS | Required with certificate-path when server requires client cert | |
| koldan.session-history-post-diarization.trust-cert-collection-path | Path to trusted CA certificates file (PEM) to validate server certificate | ||
| koldan.session-history-post-diarization.audio-chunk-size-bytes | Chunk size in bytes for streaming audio data to the diarization server | 32768 (32 KB) | Reasonable for PCM audio streaming |
| koldan.session-history-post-diarization.completion-timeout-ms | Deadline (in milliseconds) for diarization to complete | 180000 | Equivalent to 3 minutes |
Speech Services: Punctuation & Capitalization (PNCP)
These properties control the optional punctuation and capitalization gRPC dependency. Validate endpoint reachability, capacity, timeout, and TLS before enabling it.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.speech-services.punctuation-capitalization.enabled | Whether the punctuation & capitalization service is enabled | false | |
| koldan.speech-services.punctuation-capitalization.uri | URI of the PNCP server (host:port) | localhost:7500 | Example values: localhost:7500, dns:///example.com:7500, static://addr1:7500,addr2:7500 |
| koldan.speech-services.punctuation-capitalization.load-balancing-policy | Sets the load balancing policy for the connection | round_robin | pick_first, round_robin |
| koldan.speech-services.punctuation-capitalization.connection-timeout-ms | TCP connection timeout in milliseconds | 5000 | |
| koldan.speech-services.punctuation-capitalization.keep-alive-time-ms | Keep-alive ping interval in milliseconds | 30000 | |
| koldan.speech-services.punctuation-capitalization.keep-alive-timeout-ms | Keep-alive ping timeout in milliseconds | 5000 | |
| koldan.speech-services.punctuation-capitalization.max-inbound-message-size | Maximum inbound message size accepted by the client channel (bytes) | 4194304 (4 MiB) | |
| koldan.speech-services.punctuation-capitalization.ssl-enabled | Enable TLS for the client connection to the PNCP server | false | |
| koldan.speech-services.punctuation-capitalization.certificate-path | Path to client certificate file (PEM) used for mTLS | Required when ssl-enabled=true and server requires client cert | |
| koldan.speech-services.punctuation-capitalization.private-key-path | Path to client private key file (PEM) used for mTLS | Required with certificate-path when server requires client cert | |
| koldan.speech-services.punctuation-capitalization.trust-cert-collection-path | Path to trusted CA certificates file (PEM) to validate server certificate | ||
| koldan.speech-services.punctuation-capitalization.completion-timeout-ms | Deadline (in milliseconds) for punctuation/capitalization to complete | 600000 | Default: 10 minutes |
Speech Services: Transcription Segmentation
These properties set the default size and pause boundaries of readable transcription results. Changes alter client-visible output; validate them against representative audio before production rollout.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.speech-services.transcription-segmentation.enabled | Whether readable segmentation is enabled by default for transcription jobs | true | Per-job transcription.segmentation: "raw" bypasses this behavior |
| koldan.speech-services.transcription-segmentation.min-pause-seconds | Pause longer than this value splits one speaker's words into separate speech runs | 0.7 | A pause exactly equal to this value does not split the run |
| koldan.speech-services.transcription-segmentation.paragraph-pause-seconds | Pause at least this long starts a new paragraph for the same speaker | 2.0 | Applied after speech runs and short remarks have been identified |
| koldan.speech-services.transcription-segmentation.max-remark-duration-seconds | Speech runs shorter than this duration are treated as interrupting remarks | 3.0 | A remark flushes open speaker paragraphs; a run exactly this long is a monologue |
| koldan.speech-services.transcription-segmentation.strict-chronology | Whether speaker transitions force open paragraphs to close in strict timeline order | false | Can produce many short segments during overlapping speech |
| koldan.speech-services.transcription-segmentation.max-segment-duration-seconds | Final safety cap for readable segment duration, in seconds | 30.0 | Applied after readable composition; values less than or equal to zero disable the cap |
| koldan.speech-services.transcription-segmentation.max-words-per-segment | Final safety cap for words in one readable segment | 80 | Applied after readable composition; values less than or equal to zero disable the cap |
Cryptographic root properties
These properties are mandatory production inputs. Generate them before the first startup and deliver them through the controlled process in Configuration and secrets. The packaged values are development fallbacks, not production secrets.
| Property | Operational effect | Default | Production requirement |
|---|---|---|---|
| koldan.security.encryption-key | Base64-encoded AES-256 key used to protect sensitive values persisted in PostgreSQL | Built-in development value | Replace with the Base64 encoding of exactly 32 random bytes. Keep it identical across workloads and preserve it with the database recovery set. Do not change it after encrypted data exists without a tested re-encryption procedure. |
API Keys
These properties control API-key authentication through the X-API-Key header. Replace the default HMAC secret before accepting API keys, store it as sensitive data, and plan key replacement if the secret is exposed.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.api.api-keys.enabled | Enable API Key authentication. When enabled, requests can authenticate using X-API-Key header. | true | |
| koldan.api.api-keys.hmac-secret | HMAC-SHA256 secret used to hash API keys for storage and validation. | Built-in development value | Replace before issuing any production API key. Keep it identical across HTTP and gRPC replicas. Changing it invalidates every existing API key. |
| koldan.api.api-keys.default-scopes | Default scopes (roles) assigned to API keys when not explicitly specified during creation. | koldan-user | Comma-separated list of role names |
| koldan.api.api-keys.key-prefix | The prefix for generated API keys. | kk- | |
| koldan.api.api-keys.key-length | The length of the random part of the API key (excluding prefix). | 64 | Total key length = prefix length + key-length |
| koldan.api.api-keys.header-name | HTTP/gRPC metadata header read for API-key authentication. | X-API-Key | Coordinate any change with every API client and ingress policy. |
| koldan.api.api-keys.max-active-keys-per-user | Maximum number of active (non-revoked, non-expired) API keys allowed per user. Set to 0 or negative to disable. | 15 | Returns HTTP 429 when limit is reached |
Workflow workers
These settings control Temporal client configuration and the management endpoint used by worker workloads. Replica, resource, concurrency, and database-pool controls are Helm values; see Temporal, Scaling and capacity, and Helm values.
| Property | Description | Default | Notes |
|---|---|---|---|
| spring.temporal.* | Temporal Spring Boot properties | - | |
| koldan.workflows-worker.management-port | Actuator management port | 5196 | |
| koldan.workflows-worker.transcription.activity-heartbeat-timeout | Shared heartbeat timeout for long-running activities | 4m | Spring duration; must be longer than 10 seconds. Changes apply to newly started transcription workflows. |
The chart generates a separate spring.temporal.workers configuration for each worker pool. Do not override that worker list, its task types, task-queue names, or pool assignments through config. Use workerPools.<pool>.capacityOverrides for supported executor and bounded-poller controls and workerPools.<pool>.managementPort for the per-pool management endpoint. The chart-defined mapping, workflow-cache ceiling, and automatic affected-pool rollout procedure are documented in Temporal.
Data-retention cleanup
These properties control whether expired data is purged automatically and how often the cleanup runs. Disabling scheduled cleanup can cause retained data and storage consumption to grow.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.retention-cleanup-workflow.enabled | Enable recurring cleanup of data that has exceeded its effective retention period | true | When false, scheduled cleanup does not run |
| koldan.retention-cleanup-workflow.cron | Cron expression (Temporal cron format) controlling how often the cleanup workflow runs | 0 * * * * |
Default: every hour at minute 0 |
Webhook delivery
These properties control outbound webhook delivery, retries, and timeouts. Account for the longest retry window during incident response and destination maintenance.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.webhooks.retry.max-attempts | Maximum number of delivery attempts before marking webhook as exhausted | 10 | |
| koldan.webhooks.retry.initial-interval | Delay before the first retry attempt | 5s | |
| koldan.webhooks.retry.backoff-coefficient | Multiplier applied to the interval after each failed attempt | 3.2 | Produces an approximate schedule: 5s → 30s → 1m → 5m → 15m → 45m → 2h → 6h → 24h |
| koldan.webhooks.retry.maximum-interval | Upper bound on the delay between retry attempts | 24h | |
| koldan.webhooks.delivery.connect-timeout | HTTP connect timeout for webhook POST requests | 10s | |
| koldan.webhooks.delivery.read-timeout | HTTP read timeout for webhook POST requests | 30s |
Webhook security
Keep destination allowlisting, private-address blocking, redirect blocking, and certificate verification enabled unless a reviewed network requirement calls for a narrower exception.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.webhooks.security.url-allow-pattern | Regex pattern for permitted webhook URLs; non-matching destinations are rejected at registration and delivery | ^https://.* |
Keep the expression restricted to approved HTTPS destinations |
| koldan.webhooks.security.block-private-ips | Block webhook URLs that resolve to private addresses as an SSRF control | true | Disabling this permits destinations on private networks and requires a security review |
| koldan.webhooks.security.max-redirects | Maximum number of HTTP redirects followed during delivery | 0 | Zero blocks redirects and prevents them bypassing destination checks |
| koldan.webhooks.security.ssl-verify | Verify the destination certificate during webhook delivery | true | Disabling verification permits untrusted certificates and requires a security review |
Data-retention policy defaults
These values seed retention policies for newly created tenants. Values are days before purge. More-specific runtime policy can override them, so changing an application default does not prove that existing tenant or user policy changed. Include every retained data class in storage forecasts and restore testing.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.api.data-retention.deleted-file-content-retention-days | Days a soft-deleted file is retained before permanent purge | 30 | |
| koldan.api.data-retention.file-content-retention-days | Days after file creation before the source media binary is automatically discarded | 90 | |
| koldan.api.data-retention.completed-transcription-result-retention-days | Days a completed transcription result is retained | 90 | |
| koldan.api.data-retention.failed-transcription-retention-days | Days a failed/cancelled transcription is retained before auto-deletion | 30 | |
| koldan.api.data-retention.deleted-transcription-retention-days | Days a soft-deleted transcription's data is retained before permanent purge | 0 | 0 means data is purged immediately upon soft-deletion |
| koldan.api.data-retention.completed-summary-result-retention-days | Days a completed summary result is retained | 90 | |
| koldan.api.data-retention.failed-summary-retention-days | Days a failed/cancelled summary is retained before auto-deletion | 30 | |
| koldan.api.data-retention.deleted-summary-retention-days | Days a soft-deleted summary's data is retained before permanent purge | 30 | |
| koldan.api.data-retention.completed-translation-result-retention-days | Days a completed translation result is retained | 90 | |
| koldan.api.data-retention.failed-translation-retention-days | Days a failed/cancelled translation is retained before auto-deletion | 30 | |
| koldan.api.data-retention.deleted-translation-retention-days | Days a soft-deleted translation's data is retained before permanent purge | 30 | |
| koldan.api.data-retention.completed-listening-audio-retention-days | Days a completed listening audio MP3 is retained after creation | 90 | |
| koldan.api.data-retention.deleted-listening-audio-retention-days | Days a soft-deleted listening audio is retained before permanent purge | 30 | |
| koldan.api.data-retention.listening-audio-content-retention-days | Days after creation before a listening audio MP3 is automatically discarded | 90 | |
| koldan.api.data-retention.text-translation-history-retention-days | Days a text translation history record is retained before automatic purge | 90 | |
| koldan.api.data-retention.deleted-text-translation-retention-days | Days a soft-deleted text translation's data is retained before permanent purge | 30 | |
| koldan.api.data-retention.completed-speaker-verification-retention-days | Days completed speaker verification records are retained | 90 | |
| koldan.api.data-retention.failed-speaker-verification-retention-days | Days failed speaker verification records are retained before auto-delete | 30 | |
| koldan.api.data-retention.deleted-speaker-verification-retention-days | Days soft-deleted speaker verification data is retained before purge | 0 | |
| koldan.api.data-retention.speaker-verification-probe-audio-retention-days | Days verification probe recordings are retained | 7 | 0 means probe audio is not retained |
| koldan.api.data-retention.ready-speaker-enrollment-recording-retention-days | Days READY enrollment recordings are retained before recording discard | 365 | |
| koldan.api.data-retention.failed-speaker-enrollment-retention-days | Days failed/cancelled enrollments are retained before auto-delete | 30 | |
| koldan.api.data-retention.deleted-speaker-enrollment-retention-days | Days soft-deleted enrollments are retained before purge | 30 | |
| koldan.api.data-retention.archived-speaker-enrollment-retention-days | Days archived speaker enrollments are retained | 365 | |
| koldan.api.data-retention.inactive-model-voice-print-retention-days | Days inactive voice prints are retained before auto-delete | 30 | |
| koldan.api.data-retention.failed-voice-print-retention-days | Days failed voice prints are retained before auto-delete | 30 | |
| koldan.api.data-retention.deleted-voice-print-retention-days | Days soft-deleted voice prints are retained before purge | 7 | |
| koldan.api.data-retention.deleted-speaker-retention-days | Days soft-deleted speaker metadata is retained before purge | 30 |
Audit-log retention
These global values set audit-event retention by importance. Confirm that they satisfy the site's security, legal, and storage requirements before changing them.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.audit.retention.low-days | Days to retain LOW importance audit events | 7 | Health checks, routine reads, OPTIONS/HEAD |
| koldan.audit.retention.medium-days | Days to retain MEDIUM importance audit events | 30 | Standard CRUD, configuration reads, search |
| koldan.audit.retention.high-days | Days to retain HIGH importance audit events | 180 | File uploads, deletions, admin writes |
| koldan.audit.retention.critical-days | Days to retain CRITICAL importance audit events | 365 | Auth failures, impersonation, role changes |
Audit cleanup uses the data-retention cleanup schedule. Unlike the preceding retention defaults, these values are global rather than tenant- or user-specific.
LLM and session-history AI properties
These properties select LLM endpoints, credentials, models, timeouts, and generation defaults. Provider names and model identifiers are external-service contracts and can change; validate a supported request after every provider change. See LLM providers.
LLM providers
LLM providers are configured under koldan.llm.providers.<provider-id>. Each provider has a type (openai, azure-openai, ollama, bedrock, gemini, anthropic, or vertex-ai) and type-specific settings.
OpenAI Provider Properties
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.llm.providers.\<id>.type | Provider type | Must be openai |
|
| koldan.llm.providers.\<id>.openai.api-key | OpenAI API key | Required | |
| koldan.llm.providers.\<id>.openai.model | Model name (e.g. gpt-4) |
Required unless overridden by task config | |
| koldan.llm.providers.\<id>.openai.base-url | Custom base URL for OpenAI-compatible endpoints | Optional | |
| koldan.llm.providers.\<id>.openai.temperature | Sampling temperature | Optional | |
| koldan.llm.providers.\<id>.openai.timeout | Request timeout | 5m | |
| koldan.llm.providers.\<id>.openai.service-tier | OpenAI service tier (e.g. priority) |
Optional. When not set, no service tier is sent to the OpenAI API | |
| koldan.llm.providers.\<id>.openai.reasoning-effort | Reasoning effort for reasoning models (e.g. low, medium, high) |
Optional. When not set, no reasoning effort is sent to the OpenAI API |
Azure OpenAI Provider Properties
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.llm.providers.\<id>.type | Provider type | Must be azure-openai |
|
| koldan.llm.providers.\<id>.azure-openai.endpoint | Azure OpenAI endpoint, e.g. https://<resource>.openai.azure.com/ |
Required | |
| koldan.llm.providers.\<id>.azure-openai.api-key | Azure OpenAI API key | Required unless use-azure-credential=true |
|
| koldan.llm.providers.\<id>.azure-openai.use-azure-credential | Use Microsoft Entra / managed identity credentials instead of an API key | false | Optional |
| koldan.llm.providers.\<id>.azure-openai.deployment-name | Azure OpenAI deployment name | Required unless overridden by task config | |
| koldan.llm.providers.\<id>.azure-openai.service-version | Azure OpenAI API service version, e.g. 2024-10-21 |
Optional | |
| koldan.llm.providers.\<id>.azure-openai.temperature | Sampling temperature | Optional | |
| koldan.llm.providers.\<id>.azure-openai.top-p | Nucleus sampling parameter | Optional | |
| koldan.llm.providers.\<id>.azure-openai.max-tokens | Maximum output tokens | Optional | |
| koldan.llm.providers.\<id>.azure-openai.max-completion-tokens | Maximum completion tokens for reasoning-capable deployments | Optional | |
| koldan.llm.providers.\<id>.azure-openai.reasoning-effort | Reasoning effort for supported deployments (low, medium, high) |
Optional | |
| koldan.llm.providers.\<id>.azure-openai.timeout | Request timeout | 5m | Optional |
| koldan.llm.providers.\<id>.azure-openai.max-retries | Maximum retry attempts | Optional |
Ollama Provider Properties
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.llm.providers.\<id>.type | Provider type | Must be ollama |
|
| koldan.llm.providers.\<id>.ollama.base-url | Ollama server base URL | http://localhost:11434 | Required |
| koldan.llm.providers.\<id>.ollama.model | Model name | Required unless overridden by task config | |
| koldan.llm.providers.\<id>.ollama.temperature | Sampling temperature | Optional | |
| koldan.llm.providers.\<id>.ollama.timeout | Request timeout | 5m | |
| koldan.llm.providers.\<id>.ollama.think | Enable thinking/reasoning mode for supported models (e.g. DeepSeek R1). true enables, false disables, null uses model default |
Optional | |
| koldan.llm.providers.\<id>.ollama.return-thinking | Whether to return thinking/reasoning text separately in the response | Optional |
Google AI Gemini Provider Properties
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.llm.providers.\<id>.type | Provider type | Must be gemini |
|
| koldan.llm.providers.\<id>.gemini.api-key | Google AI API key | Required | |
| koldan.llm.providers.\<id>.gemini.model | Model name (e.g. gemini-pro, gemini-2.5-flash) |
Required unless overridden by task config | |
| koldan.llm.providers.\<id>.gemini.base-url | Custom API base URL (for proxies or custom endpoints) | Optional | |
| koldan.llm.providers.\<id>.gemini.temperature | Sampling temperature | Optional | |
| koldan.llm.providers.\<id>.gemini.max-output-tokens | Maximum number of output tokens | Optional | |
| koldan.llm.providers.\<id>.gemini.timeout | Request timeout | 5m | |
| koldan.llm.providers.\<id>.gemini.thinking-config.include-thoughts | Whether to include thinking/reasoning in the response | Optional | |
| koldan.llm.providers.\<id>.gemini.thinking-config.thinking-budget | Token budget for the thinking/reasoning phase | Optional | |
| koldan.llm.providers.\<id>.gemini.thinking-config.thinking-level | Thinking level (e.g. low, medium, high) |
Optional |
Anthropic (Claude) Provider Properties
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.llm.providers.\<id>.type | Provider type | Must be anthropic |
|
| koldan.llm.providers.\<id>.anthropic.api-key | Anthropic API key | Required | |
| koldan.llm.providers.\<id>.anthropic.model | Model name (e.g. claude-sonnet-4-20250514, claude-3-5-haiku-20241022) |
Required unless overridden by task config | |
| koldan.llm.providers.\<id>.anthropic.base-url | Custom API base URL (for proxies or custom endpoints) | Optional | |
| koldan.llm.providers.\<id>.anthropic.temperature | Sampling temperature | Optional | |
| koldan.llm.providers.\<id>.anthropic.top-p | Nucleus sampling parameter | Optional | |
| koldan.llm.providers.\<id>.anthropic.top-k | Top-k sampling parameter | Optional | |
| koldan.llm.providers.\<id>.anthropic.max-tokens | Maximum number of output tokens | Optional | |
| koldan.llm.providers.\<id>.anthropic.timeout | Request timeout | 5m |
Provider selection
These capabilities reference a configured provider ID and can override its default model.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.llm.session-history-summary.provider | Provider ID to use for summary generation | ||
| koldan.llm.session-history-summary.model | Model override for summary generation | ||
| koldan.llm.session-history-autotitle.provider | Provider ID to use for autotitle generation | ||
| koldan.llm.session-history-autotitle.model | Model override for autotitle generation |
Generation defaults
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.llm.session-history-autotitle.max-words-in-transcript | Maximum number of words from transcript to use for autotitling | 72 | |
| koldan.llm.session-history-summary.minimum-words-count | Minimum number of words required in a session to allow summary generation. Sessions with fewer words will be rejected with a validation error. | 20 | |
| koldan.llm.session-history-summary.system-prompt-template | Default system prompt used for summary generation when no language-specific or tenant-specific override is found. | Please summarize the following conversation: |
|
| koldan.llm.session-history-summary.user-prompt-template | Default user prompt template used for summary generation. Uses {{transcript}} placeholder. |
TRANSCRIPT:\n{{transcript}} |
|
| koldan.llm.session-history-summary.user-custom-prompt-template | Default user prompt template when a custom user request is provided. Uses {{userCustomPrompt}} and {{transcript}} placeholders. |
USER CUSTOM ADDITIONAL REQUESTS: {{userCustomPrompt}}\n\nTRANSCRIPT:\n{{transcript}} |
|
| koldan.llm.session-history-autotitle.system-prompt-template | Default system prompt used for autotitle generation when no language-specific or tenant-specific override is found. | Please provide a short, descriptive title for the following conversation (maximum 10 words): |
|
| koldan.llm.session-history-autotitle.user-prompt-template | Default user prompt template used for autotitle generation. Uses {{transcript}} placeholder. |
TRANSCRIPT:\n{{transcript}} |
ZooKeeper
ZooKeeper provides discovery for Koldan-managed internal engines. Deployments without those engines can disable it; API workloads then create no Curator client and report no discovered engines. Keep it enabled for internal-engine and Koldan Desktop speech deployments.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.zookeeper.enabled | Enable ZooKeeper-backed internal-engine discovery | true | Set to false only when no Koldan-managed internal engines are deployed. |
| koldan.zookeeper.url | ZooKeeper connection string used for coordination | localhost:2181 |
Session concurrency limits
These limits protect shared capacity by constraining simultaneous sessions per user and across the site. Set them below verified API and engine capacity, leaving headroom for failover and maintenance.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.concurrent-session-restriction.enabled | Enable per-user/global concurrent session limits | false | |
| koldan.concurrent-session-restriction.max-sessions-per-user | Max concurrent sessions per user | 3 | |
| koldan.concurrent-session-restriction.max-global-sessions | Max total concurrent sessions across users | 100 | |
| koldan.concurrent-session-restriction.acquire-timeout-ms | Timeout (milliseconds) waiting for a session slot and acquire lock | 400 |
Task executors
These properties bound the shared asynchronous executor and determine whether shutdown waits for submitted work. Validate changes under representative load and keep shutdown behavior aligned with pod termination grace periods.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.default-task-executor.core-pool-size | Baseline asynchronous executor thread count | 2 | |
| koldan.default-task-executor.max-pool-size | Maximum asynchronous executor thread count | 8 | Must be greater than or equal to the core pool size |
| koldan.default-task-executor.wait-for-tasks-to-complete-on-shutdown | Wait for submitted executor work during shutdown | true | Account for this wait in the workload termination grace period |
K2 engine configuration
These properties control the runtime resources and recognition behavior of K2 engine instances. Treat changes as workload-specific tuning: test quality, latency, CPU/GPU memory, and concurrency before rollout. Use Helm instance values for replicas, placement, and container resources.
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.engine.k2.config.sample-rate | Audio sample rate used by the recognizer | 16000 | |
| koldan.engine.k2.config.decoding-method | Decoder decoding method | greedy_search | |
| koldan.engine.k2.config.initial-noise-duration | Duration (in deciseconds) of audio that will be artificially inserted for each transcription segment before the audio received from the client | 0 | |
| koldan.engine.k2.config.final-noise-duration | Duration (in deciseconds) of synthetic audio appended to each transcription segment | 6 | Validate recognition quality and latency after changing it |
| koldan.engine.k2.config.batch-size | Decoder batch size | 24 | |
| koldan.engine.k2.config.hot-words.enabled | Enable hot words boosting | false | |
| koldan.engine.k2.config.hot-words.file | File path to hotwords file | ||
| koldan.engine.k2.config.hot-words.default-score | Score applied when a hotword file entry does not specify one | 1.5 | |
| koldan.engine.k2.config.hot-words.modeling-unit | Hot words modeling unit | bpe | |
| koldan.engine.k2.config.endpointing.enabled | Enable endpointing detection | true | |
| koldan.engine.k2.config.feature-dim | Feature dimension | 80 | |
| koldan.engine.k2.config.max-active | Max active tokens/graphs | 3000 | |
| koldan.engine.k2.config.num-threads | Threads used by decoder | 4 | |
| koldan.engine.k2.config.max-active-paths | Max active paths | 4 | |
| koldan.engine.k2.config.lm-model | External LM model path | ||
| koldan.engine.k2.config.lm-scale | Language model scale | 0.5 | |
| koldan.engine.k2.config.model-type | Model type | zipformer2 | |
| koldan.engine.k2.config.provider | Runtime provider (cpu/cuda) | cpu | CPU/CUDA |
| koldan.engine.k2.config.device-id | Device ID for provider (usually for CUDA) | 0 |
Speaker verification services
These properties define resource limits and decision thresholds for speaker verification. Threshold changes alter client-visible outcomes; validate them against an approved evaluation set before production rollout.
Voice-print processing
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.speaker-services.verification.voice-print.minimum-usable-enrollments | Minimum number of READY enrollments required to create a voice print | 1 | |
| koldan.speaker-services.verification.voice-print.recommended-enrollments | Recommended number of enrollments for optimal voice-print quality | 3 |
Verification thresholds
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.speaker-services.verification.strict-accept-threshold | Accept threshold for STRICT mode | 0.85 | |
| koldan.speaker-services.verification.strict-review-threshold | Review threshold for STRICT mode | 0.75 | |
| koldan.speaker-services.verification.balanced-accept-threshold | Accept threshold for BALANCED mode (default) | 0.70 | |
| koldan.speaker-services.verification.balanced-review-threshold | Review threshold for BALANCED mode | 0.55 | |
| koldan.speaker-services.verification.lenient-accept-threshold | Accept threshold for LENIENT mode | 0.55 | |
| koldan.speaker-services.verification.lenient-review-threshold | Review threshold for LENIENT mode | 0.40 | |
| koldan.speaker-services.verification.probe-audio-retention-days | Legacy global probe-retention fallback; effective retention now uses koldan.api.data-retention.speaker-verification-probe-audio-retention-days |
7 | Prefer data-retention policy |
Audio submission limits
| Property | Description | Default | Notes |
|---|---|---|---|
| koldan.speaker-services.verification.max-enrollment-upload-size-bytes | Maximum enrollment audio size for direct multipart uploads | 5242880 | 5 MB |
| koldan.speaker-services.verification.max-verification-upload-size-bytes | Maximum verification probe audio size for direct multipart uploads | 5242880 | 5 MB |
| koldan.speaker-services.verification.uri.max-size-bytes | Maximum enrollment/probe audio size for URI imports | 5242880 | 5 MB |