Skip to main content
Configuration lives in config.yml. On production servers it must be at /kair_voice_config/config.yml. The app validates all fields at startup and refuses to boot on missing or invalid config.

Full reference

rag.enable_thinking / moderator_agent.enable_thinking (default false) disables reasoning-model “thinking” on the OpenAI-compatible agent_client path (e.g. IONOS); it is a per-worker knob. reasoning_effort: minimal/low alone does not reliably stop vLLM-hosted reasoning models (Qwen3, DeepSeek-R1 — IONOS’s hosted reasoning models included) from emitting hidden chain-of-thought; this sends the dedicated chat_template_kwargs: {"enable_thinking": false} switch those backends expect.

Key decisions

Runtime overrides

Admins can override the following without restarting, via the System page or the admin API:
  • Transcription client, Scaleway model names
  • Rag agent client, embedding client, LLM model, embedding model, Ollama URL
  • Summarisation Ollama URL
All other settings require a config file change + service restart.

Transport security validation

All processes call kair_voice_core::transport_security::validate_transport_security at boot, right after logging starts and before any connection is made. In development (app.env: development) the check is skipped. In staging and production every rule below is currently warn-only (TransportChecks::into_warn_mode, logged as Transport security (warn-only): …) while TLS is rolled out to the db host; remove into_warn_mode() from each process’s main.rs to make them refuse to start instead. Saving an insecure AI-inference URL via the admin panel (/admin/system) is also rejected at runtime in non-development environments. See crates/core/src/transport_security.rs for the full validation logic.

S3 encryption at rest

Hetzner Object Storage does not encrypt objects by default, so every object is written with SSE-C (customer-provided key): Hetzner encrypts on write and decrypts on read, and never stores the key. A leaked bucket holds only ciphertext.
  • s3.encryption_key is required in the API and every worker (transcription, document-worker, rag-worker) and the CLI. Generate it once with openssl rand -base64 32 and share the same value everywhere.
  • Back the key up outside the platform. Without it every object is unreadable; there is no recovery. Rotating it means re-writing every object.
  • The key is attached by an SDK interceptor in core::s3_encryption, so all S3 calls made through init_s3_client are covered. Deletes need no key.
  • Browsers never see the key, so presigned S3 URLs are not used. The API checks access, then returns a short-lived signed link under /api/blob/get/<token> (playback, downloads, GDPR export) or /api/blob/put/<token> (multipart upload parts) and streams the bytes itself, decrypting on the way. Links are signed with auth.jwt_secret and expire after an hour (the export email link after 24 hours).
  • app.public_api_url must be the origin the browser reaches the API on, because these links are built from it.

Encrypting objects written before SSE-C

Run once per environment after deploying, with CONFIG_PATH pointing at that environment’s config:
It lists the production prefixes (kair-voice/production/, plus the env-less kair-voice/audio_uploads/ that multipart uploads write to and kair-voice/gdpr-exports/; override with repeatable --prefix), skips objects already under the key, downloads each remaining object keylessly, re-uploads it with SSE-C, then reads it back through the key and compares size and MD5 with the source (and the source’s MD5 with its ETag when it has a plain one). Transient network errors are retried; if the encrypted copy still can’t be verified, the plaintext temp file is kept and its path printed, because the bucket original has already been overwritten. Objects are processed in parallel (--concurrency, default 8, max 64; each in-flight object uses up to its size in temp disk) with a progress line every 100 objects. Safe to re-run; failed objects are counted and retried on the next run. Only counts are printed, never object keys (they contain file names).

S3 lifecycle

Audio files are large. Configure automatic deletion after 30 days:

Audio model sizes

Whisper model RAM requirements per worker: Workers load the model once at startup. 3 concurrent workers on a 64 GB machine can each hold a large-v3 model.