Configuration & Environment Variables
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The tldw_server configuration system is designed to provide a flexible and robust mechanism for managing application behavior across various environments, ranging from local development to production-scale multi-user deployments. The system centralizes settings for authentication modes, database connections, API providers, and internal module behaviors (e.g., RAG, TTS, and Embeddings).
The architecture relies on a strictly defined precedence chain to ensure deterministic behavior when configuration values are defined in multiple locations. This system allows for global defaults while permitting granular overrides through configuration files and environment variables. Key components include the primary config.txt file, a .env file for secrets, and module-specific YAML configurations.
Sources: Docs/Architecture.md, Docs/Product/Completed/Config_Normalization.md:1-15
Configuration Architecture & Precedence
The project utilizes a normalized configuration root resolver to eliminate per-module logic drift. This architecture ensures that all modules—including TTS, Embeddings, and Evaluations—share the same resolution rules.
Precedence Chain
When the server resolves a configuration value, it follows a specific hierarchy. A higher-level source will always override a lower-level one:
- Environment Variables: Temporary or container-level overrides (e.g., CI/Docker).
.envFile: Used primarily for secrets such as API keys and JWT tokens.config.txt: The primary file for runtime tuning (chunking, RAG, provider URLs).- Module YAML: Specific settings for sub-modules (e.g.,
tts_providers_config.yaml). - Defaults: Hardcoded fallback values within the application logic.
Sources: Docs/Product/Completed/Config_Normalization.md:23-45, Docs/Plans/2026-03-30-ftue-audit-v2-implementation-plan.md:300-310
Visualizing Configuration Flow
The following diagram illustrates how the configuration resolver determines the final effective settings used by core services.
The diagram shows the hierarchical merging of configuration sources into a single effective state used by the server.
Sources: Docs/Product/Completed/Config_Normalization.md:85-105, Docs/Architecture.md
Core Configuration Elements
1. Authentication Configuration
Authentication is managed primarily through the AUTH_MODE variable, which dictates whether the server operates in personal or multi-tenant mode.
| Variable | Type | Description |
|---|---|---|
AUTH_MODE | String | single_user (API Key) or multi_user (JWT/PostgreSQL). |
SINGLE_USER_API_KEY | Secret | Required key for single_user mode access. |
JWT_SECRET_KEY | Secret | Used for signing tokens in multi_user mode. |
DATABASE_URL | URL | Connection string for the AuthNZ database (SQLite or Postgres). |
Sources: Docs/Architecture.md, Env_Vars.md, Docs/Plans/2026-03-30-ftue-audit-v2-implementation-plan.md:65-80
2. Provider & API Keys
tldw_server supports over 16 LLM providers. These are configured via environment variables or the [Providers] section in config.txt.
# Example .env secret configuration
OPENAI_API_KEY=sk-proj-xxxx
ANTHROPIC_API_KEY=x-api-key-xxxx
JWT_SECRET_KEY=generated-secret-string
Sources: CLAUDE.md, AGENTS.md, Docs/Plans/2026-03-30-ftue-audit-v2-implementation-plan.md:65-80
3. Database & Storage Paths
The server differentiates between centralized authentication data and per-user content data.
| Setting | Default Path / Value | Description |
|---|---|---|
USER_DB_BASE_DIR | Databases/user_databases/ | Root directory for per-user SQLite and vector stores. |
DATABASE_URL | sqlite:///./Databases/users.db | Default AuthNZ database location. |
TLDW_CONFIG_DIR | (Auto-resolved) | Explicit override for the configuration root directory. |
Sources: Docs/Architecture.md, Docs/Product/Completed/Config_Normalization.md:65-75
Root Directory Resolution Logic
The system employs a deterministic sequence to find the configuration root, which is critical for both packaged installs and development environments.
The flowchart describes the sequential logic used by the shared resolver to locate the application's configuration files.
Sources: Docs/Product/Completed/Config_Normalization.md:65-80
Admin Diagnostics: Effective Config API
To assist administrators in troubleshooting precedence issues, the server provides an authenticated, redacted API endpoint that exposes the current configuration state.
- Endpoint:
GET /api/v1/admin/config/effective - Access Control: Restricted to users with
adminprivileges. - Functionality: Returns values with metadata indicating the source (env, config, yaml, or default) and redacts sensitive keys matching patterns like
*key*,*secret*, or*password*.
Sources: Docs/Product/Completed/Config_Normalization.md:120-145
Summary
The tldw_server configuration system provides a structured, multi-layered approach to environment management. By enforcing a single precedence chain (Environment > .env > config.txt > Module YAML), the architecture ensures consistency across the server's diverse core modules. This setup allows for secure secret management via .env while maintaining easily tunable runtime parameters in config.txt, all supported by a centralized resolver that handles diverse deployment scenarios from local dev to production containers.
Sources: Docs/Product/Completed/Config_Normalization.md, Docs/Plans/2026-03-30-ftue-audit-v2-implementation-plan.md:300-310