Configuration Management in AnythingLLM orchestrates all system settings through a centralized validation and persistence pipeline. This system manages 200+ environment variables spanning LLM providers, vector databases, embedding engines, authentication, and application behavior. The architecture implements dual persistence (environment variables + database), validation middleware, and lifecycle hooks to ensure data integrity across configuration changes.
Related Documentation:
AnythingLLM implements a dual persistence model where configuration exists both as runtime environment variables (process.env) and as database records (SystemSettings model). This architecture allows configuration to survive server restarts while maintaining runtime performance.
Sources: server/utils/helpers/updateENV.js1-1338 server/models/systemSettings.js1-1079
The KEY_MAPPING object defines all configurable fields in the system. Each key maps to an environment variable name, validation functions, and optional lifecycle hooks.
| Property | Type | Purpose |
|---|---|---|
envKey | string | Environment variable name (e.g., "LLM_PROVIDER") |
checks | array | Validation functions executed before update |
preUpdate | array | Functions executed before setting process.env |
postUpdate | array | Functions executed after setting process.env |
postSettled | array | Functions executed after all updates complete |
Sources: server/utils/helpers/updateENV.js7-830
The KEY_MAPPING contains configuration groups for each integration:
LLM Providers (30+ providers):
OpenAiKey, OpenAiModelPref updateENV.js13-20AzureOpenAiEndpoint, AzureOpenAiKey, AzureOpenAiModelPref updateENV.js22-50AnthropicApiKey, AnthropicModelPref, AnthropicCacheControl updateENV.js53-69OllamaLLMBasePath, OllamaLLMModelPref, OllamaLLMTokenLimit updateENV.js120-139Vector Databases (10+ databases):
ChromaEndpoint, ChromaApiHeader, ChromaApiKey updateENV.js343-354PineConeKey, PineConeIndex updateENV.js389-396PGVectorConnectionString, PGVectorTableName updateENV.js438-447Embedding Engines:
EmbeddingEngine, EmbeddingModelPref updateENV.js292-305OllamaEmbeddingBatchSize updateENV.js314-317Sources: server/utils/helpers/updateENV.js7-830
The validation system implements defense-in-depth with multiple validation layers executed sequentially.
| Function | Purpose | Example |
|---|---|---|
isNotEmpty() | Ensures value is non-empty string | Used for all API keys |
nonZero() | Ensures numeric value > 0 | Token limits, chunk sizes |
isInteger() | Validates integer values | Keep-alive timeouts |
isValidURL() | Validates URL format | Base paths, endpoints |
validDockerizedUrl() | Special validation for Docker environments | Checks port availability from container |
supportedLLM() | Whitelist check for LLM providers | Validates against 46 supported providers |
supportedVectorDB() | Whitelist check for vector databases | Validates against 10 supported databases |
supportedEmbeddingModel() | Whitelist check for embedding engines | Validates against 13 supported engines |
Sources: server/utils/helpers/updateENV.js832-1060
The validDockerizedUrl() function performs special checks when AnythingLLM runs in Docker:
Sources: server/utils/helpers/updateENV.js1024-1047
PGVector connections undergo real-time validation:
Sources: server/utils/helpers/updateENV.js1116-1132
The updateENV() function is the central orchestrator for all configuration changes. It implements a six-stage pipeline with error handling and rollback capabilities.
Sources: server/utils/helpers/updateENV.js1164-1220
Lifecycle hooks enable side effects and custom processing at specific points in the update pipeline.
Pre-update hooks execute before process.env is modified. They validate external resources or perform setup operations.
| Hook | When Used | Purpose |
|---|---|---|
validatePGVectorConnectionString | PGVector connection changes | Tests database connectivity |
validatePGVectorTableName | PGVector table changes | Verifies table accessibility |
Telemetry.sendTelemetry | DisableTelemetry set to true | Sends final telemetry event |
Sources: server/utils/helpers/updateENV.js438-447 updateENV.js557-561
Post-update hooks execute after process.env is modified but before persistence. They handle side effects and cascading updates.
| Hook | Triggered By | Action |
|---|---|---|
handleVectorStoreReset | VectorDB, EmbeddingEngine, EmbeddingModelPref | Purges all vector namespaces when storage configuration changes |
downloadEmbeddingModelIfRequired | EmbeddingModelPref | Downloads native embedding models in background |
parseNvidiaNimBasePath | NvidiaNimLLMBasePath | Normalizes NVIDIA NIM URL format |
NvidiaNimLLM.setModelTokenLimit | NvidiaNimLLMModelPref | Auto-configures token limits for selected model |
FoundryLLM.unloadModelFromEngine | FoundryModelPref | Unloads previous model from Foundry engine |
FoundryLLM.cacheContextWindows | FoundryModelPref | Pre-caches context window metadata |
Sources: server/utils/helpers/updateENV.js295-305 updateENV.js698-715 updateENV.js744-752
When embedding or vector database configuration changes, the system automatically purges existing vector stores to prevent data corruption from incompatible embeddings.
Sources: server/utils/helpers/updateENV.js1062-1078
The SystemSettings model provides database persistence and application-level validation for configuration values.
Sources: server/models/systemSettings.js22-1079
| Category | Field Examples | Purpose |
|---|---|---|
| Protected | multi_user_mode, hub_api_key, onboarding_complete | Cannot be directly modified via API |
| Public | footer_data, support_email, custom_app_name | Exposed to frontend without authentication |
| Supported | All configurable fields | Valid for updateSettings() method |
Sources: server/models/systemSettings.js26-67
The validations object defines field-specific processing logic executed during _updateSettings():
Sources: server/models/systemSettings.js68-208
The currentSettings() method aggregates all configuration into a single object for frontend consumption:
Sources: server/models/systemSettings.js209-321
The dumpENV() function writes the current process.env state to the .env file, ensuring configuration survives server restarts.
dumpENV() maintains a whitelist of keys to persist:
Sources: server/utils/helpers/updateENV.js1248-1306
Sources: server/utils/helpers/updateENV.js1244-1332
The sanitizeValue() function prevents environment variable injection attacks:
Sources: server/utils/helpers/updateENV.js1309-1316
The frontend provides user interfaces for configuration management through multiple entry points.
Sources: frontend/src/pages/GeneralSettings/LLMPreference/index.jsx1-586 frontend/src/pages/OnboardingFlow/Steps/LLMPreference/index.jsx1-461
Each provider entry defines UI metadata and validation requirements:
The requiredConfig array determines which fields must be populated before the provider can be selected. This validation occurs in the frontend before submission.
Sources: frontend/src/pages/GeneralSettings/LLMPreference/index.jsx85-407
Sources: frontend/src/pages/GeneralSettings/LLMPreference/index.jsx481-540
All configuration changes are logged to the EventLogs table for audit trail purposes.
| Event Name | Triggered By | Purpose |
|---|---|---|
update_llm_provider | LLMProvider change | Track LLM provider switches |
update_embedding_engine | EmbeddingEngine change | Track embedding engine switches |
update_vector_db | VectorDB change | Track vector database switches |
telemetry_disabled | DisableTelemetry set to true | Record telemetry opt-out |
onboarding_complete | markOnboardingComplete() | Track successful onboarding |
Sources: server/utils/helpers/updateENV.js1229-1242
Configuration values are consumed throughout the application via factory functions and model methods.
Sources: server/utils/helpers/index.js84-303
Workspaces can override system-level LLM configuration for per-tenant customization:
When a workspace has overrides, getLLMProvider() is called with the workspace-specific provider/model instead of system defaults.
Sources: server/utils/helpers/index.js131-248
The .env.example files serve as templates documenting all available configuration options.
| File | Purpose |
|---|---|
server/.env.example | Native/bare-metal deployment template |
docker/.env.example | Docker deployment template with container-specific defaults |
Both files organize variables into logical sections:
The Docker .env.example includes container-specific defaults:
For services running in containers, base paths use host.docker.internal instead of localhost:
Sources: server/.env.example1-426 docker/.env.example1-423
Certain sensitive settings require force=true parameter to modify:
Protected settings:
AUTH_TOKEN - Instance passwordJWT_SECRET - Session signing keySources: server/utils/helpers/updateENV.js1020-1022
Anthropic supports prompt caching to reduce costs:
Valid values:
"none" - No caching"5m" - 5-minute cache"1h" - 1-hour cacheSources: server/utils/helpers/updateENV.js61-69
Azure OpenAI distinguishes between standard and reasoning models:
Sources: server/utils/helpers/updateENV.js42-50
The Configuration Management system implements a robust, validated pipeline for managing 200+ system settings. Key architectural decisions include:
.env filesThe updateENV() function serves as the single source of truth for configuration updates, ensuring consistency across the application.
Refresh this wiki