Koldan Server Configuration Reference

This document catalogs the custom configuration properties used across the Koldan services.

Site Properties

Site properties control basic configuration settings for the Koldan application interface and client behavior. These settings affect how the application presents itself to users.

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 set `OnlineSpeakerDiarizationSettings.enabled=true` in their recognition requests to identify and tag different speakers in real-time. Sessions requesting diarization will be rejected if disabled.	false	`online-diarization`
koldan.features.session-history-autotitle-enabled	Enables automatic session titling. When enabled, a workflow is triggered at the end of a session to automatically generate a title based on the transcript. Requires `session-history` feature to also be enabled.	false	`session-history-autotitle`
koldan.features.speech-services-enabled	Enables the speech-services REST API. When enabled, the speech-services HTTP endpoints (transcription jobs, file management, summaries, file sharing) and their supporting services are registered. When disabled, these endpoints do not exist and related beans are not loaded.	false	`speech-services`
koldan.features.multi-tenancy-enabled	Enables multi-tenancy support. When enabled, requests may specify a non-default tenant via the `X-Tenant-Id` header. When disabled, all requests are silently routed to the default tenant regardless of the header value.	false	`multi-tenancy`

S3 Object Storage

Koldan uses S3-compatible object storage to store and manage large objects such as models, audio files, and other artifacts.

The S3 integration supports any S3-compatible storage service, including AWS S3, MinIO, and other compatible implementations.

Property	Description	Default
koldan.s3.enabled	Enable loading models from S3-compatible object storage	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

Koldan uses OpenID Connect (OIDC) for authentication and authorization. OIDC is a secure identity layer built on top of OAuth 2.0 that enables Single Sign-On (SSO) and identity federation. When users access Koldan, they are redirected to authenticate with the OIDC provider, which then provides secure tokens that Koldan uses to verify the user's identity and permissions.

The default tenant OIDC properties serve two purposes:

Bootstrap: On first startup, DefaultTenantBootstrap seeds the default tenant's OIDC provider from these properties.
Engine token generation: Engine modules use the nested engine sub-properties to obtain client-credentials tokens directly from configuration, without requiring database access.

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.introspection-uri	OIDC token introspection 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

Elasticsearch is used in Koldan to index client logs. The Elasticsearch integration is mandatory for API modules to function properly.

Property	Description	Default
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

Engine-specific properties are listed below. These properties affect all types of engines (k2, slibe, etc...)

Property	Description	Default	Notes
koldan.engine.hostname	Hostname of engine for advertise to service discovery	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 TODO: move to K2 Section	-	See K2 Config section

gRPC API Service

The Koldan gRPC API service provides the core communication interface between clients and the Koldan speech recognition system. It handles streaming audio recognition requests, manages user sessions, and coordinates with speech recognition engines. It is the main API for Koldan Desktop clients and other applications that integrate with Koldan for real-time streaming.

The following properties configure the gRPC API service behavior:

Property	Description	Default	Notes
koldan.api-grpc.address	Internal address for the API gRPC server to be published to service discovery	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	gRPC server advertise SSL for external connections	`${koldan.api-grpc.ssl.enabled}`	By default, will advertise true if ssl is enabled on server
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 enable words filtering (usually insertions and illegal words) in online recognizer pipelines	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

The Koldan HTTP API service provides a REST interface for interacting with Koldan platform and a web-based administration console.

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

Default rate limit values applied when no tenant-level or user-level override exists in the database. All values represent the maximum number of allowed requests per minute. These can be overridden at the tenant or user level via the admin API; the resolution order is: user override → tenant default → 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

Session History Post-Session Diarization

Post-session diarization is used for re-processing diarization on completed session recordings using a slower but more accurate diarization model. This runs asynchronously after a session ends.

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	Default: 30 minutes

Speech Services: Punctuation & Capitalization (PNCP)

The punctuation and capitalization service enriches transcription job results with automatic punctuation and capitalization by calling a dedicated PNCP gRPC server. When enabled, the transcription workflow calls this service after decoding (and after merge/interleave when applicable). Users can individually opt in to punctuation and/or capitalization via the transcription request options.

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

API Keys

API Keys provide an alternative authentication mechanism for accessing Koldan APIs. Instead of using JWT tokens from Keycloak, clients can authenticate using a static API key passed in the X-API-Key header. This is useful for server-to-server integrations, scripts, and automated workflows where OAuth flows are impractical.

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 secret for hashing API keys, should be changed per site and rotated if api keys are compromised.	`koldan-api-key-secret-change-me-in-production`	any random string will work
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.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 Worker

Property	Description	Default	Notes
spring.temporal.*	Temporal Spring Boot properties	-
koldan.workflows-worker.management-port	Actuator management port	5196

Data Retention Cleanup Workflow

The data retention cleanup workflow runs periodically via a Temporal scheduled workflow to purge expired resources (files, transcriptions, summaries, translations, listening audio, text translations) based on per-tenant and per-user retention policies. See Retention API for full details.

Property	Description	Default	Notes
koldan.retention-cleanup-workflow.enabled	Whether the retention cleanup Temporal schedule is registered on startup	true	When false, no scheduled cleanup runs; manual purge still works
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 how webhook notifications are delivered and retried when API consumers register webhooks on transcription jobs, summaries, or file operations.

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

Security settings for webhook delivery. These protect against common attack vectors such as SSRF and man-in-the-middle attacks.

Property	Description	Default	Notes
koldan.webhooks.security.url-allow-pattern	Regex pattern for allowed webhook URLs. URLs that don't match are rejected at registration and delivery time.	`^https://.*`	Set to `.*` to allow any URL including `http://` (not recommended for production)
koldan.webhooks.security.block-private-ips	Block webhook URLs that resolve to private/internal IP addresses (SSRF protection)	true	Disable for local deployments where webhooks target localhost or internal services
koldan.webhooks.security.max-redirects	Maximum number of HTTP redirects to follow. Redirects can bypass URL whitelist and IP checks.	0	0 = redirects disabled entirely. Recommended to keep at 0 for security.
koldan.webhooks.security.ssl-verify	Whether to verify SSL certificates on webhook delivery	true	Set to `false` for local deployments using self-signed certificates

Local development override example

koldan:
  webhooks:
    security:
      url-allow-pattern: ".*"        # Allow any URL including http://
      block-private-ips: false        # Allow localhost/internal IPs
      max-redirects: 3                # Follow up to 3 redirects
      ssl-verify: false               # Accept self-signed certs

Data Retention Policy Defaults

Default data retention values used to seed newly created tenants. All values represent the number of days a resource is retained before being permanently purged. Admins can override these per-tenant and per-user via the Retention Admin API.

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

Audit Log Retention

Retention periods for audit log entries, configured per importance level. The data retention cleanup workflow automatically deletes audit records that have exceeded their configured retention period. Lower-importance events are cleaned more aggressively to keep the audit table manageable while preserving critical compliance records.

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 log cleanup runs as part of the Data Retention Cleanup Workflow on the same schedule. Unlike other retention policies, audit retention is global (not per-tenant or per-user).

LLM / Session History AI Properties

These properties configure the LLM providers and the LLM-based generation of summaries and autotitles for session history.

LLM Providers

LLM providers are configured under koldan.llm.providers.<provider-id>. Each provider has a type (openai or ollama) 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

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

Task Configuration

Tasks reference a provider by its ID and optionally override the 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

Task-Specific Properties

Property	Description	Default
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 is a centralized service for maintaining configuration information, naming, providing distributed synchronization, and providing group services. Koldan uses ZooKeeper for service discovery and coordination between its distributed microservices.

Property	Description	Default	Notes
koldan.zookeeper.url	Zookeeper connection string for coordination and discovery	localhost:2181

Sessions Concurrency Limits

Concurrent session restrictions help manage and limit the number of simultaneous speech recognition sessions that can be active at any given time. This helps prevent system overload and ensures fair resource distribution among users. The system supports both per-user limits (to prevent a single user from consuming too many resources) and global limits (to manage overall system capacity).

Property	Description	Default
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

Property	Description	Default	Notes
koldan.default-task-executor.core-pool-size	Core pool size for task executor	2	Default may be incorrect
koldan.default-task-executor.max-pool-size	Max pool size for task executor	8	Default may be incorrect
koldan.default-task-executor.wait-for-tasks-to-complete-on-shutdown	Wait for tasks on shutdown	true	Default may be incorrect

Discovery

Property	Description	Default	Notes
koldan.discovery.port	UDP discovery service port	8194

Engine K2 configuration

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 audio that will be artificially inserted for each transcription segment after the audio received from the client (tail). This value is crucial for ensuring that the last word of the speech is properly recognized.	6
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	Default hot word score (if not score not specified in hotwords file)	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	True by default for Koldan, false by default in SherpWrap
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