Skip to content

    Development documentation — this describes the current development branch. Documented behavior may not exist in the latest release.

    Configuration overview

    Configuration overview

    Section titled “Configuration overview”

    All configuration is through environment variables — there is no config file to mount. This page explains the configuration model and the authentication boundary; the full list of variables is in Environment variables.

    How settings are read

    Section titled “How settings are read”

    Configuration is read from the environment once at process start (server/config.py). Changing a variable requires restarting the container. Set variables with -e on docker run, an environment: block in Compose, or the chart’s fasterWhisper.extraEnv in Kubernetes.

    Boolean variables accept 1, true, yes, or on (case-insensitive) for true; anything else is false.

    Ports and binding

    Section titled “Ports and binding”

    The service listens on port 8000 inside the container. The python -m server entrypoint binds HOST (0.0.0.0) and PORT (8000); the Helm chart instead runs uvicorn ... --host 0.0.0.0 --port 8000 directly. Publish or map the port as your deployment requires — for example the local Compose stack maps host 8443 to container 8000 because it serves HTTPS.

    Authentication boundary

    Section titled “Authentication boundary”

    Authentication is off by default. Leaving API_KEY unset (the default) makes the API open. Setting it requires every protected route to send Authorization: Bearer <key>.

    RouteMethodRequires API_KEY when set
    /health, /readyGETNo — always open (orchestrator probes)
    /systemGETNo — always open (non-PII telemetry)
    /web, /web/*GETNo — the console loads before a key is entered
    /docs, /openapi.jsonGETNo
    /v1/audio/transcriptions, /v1/audio/translationsPOSTYes
    /v1/modelsGETYes
    /api/model/presets, /api/model/activateGET / POSTYes

    Key comparison is constant-time, and a malformed (non-ASCII) token returns a clean 401 rather than a 500. When auth is enabled, the web console stores the key in its settings and sends the bearer header on API calls; /health, /ready, and /system stay open so the console and orchestrators work before a key is present.

    Enabling API_KEY does not enable TLS, and vice versa. Use a placeholder like change-me in examples and set a strong key in production.

    Common configuration surfaces

    Section titled “Common configuration surfaces”
    Section titled “Related”