This document describes the environment variable configuration system in AnythingLLM, including the .env file structure, available configuration options, and how variables are organized and processed. AnythingLLM supports 200+ environment variables for configuring LLM providers, embedding engines, vector databases, authentication, and system behavior.
For information about how these settings are validated and persisted at runtime, see Configuration Management. For details on the dual persistence model (environment variables + database), see System Settings Architecture.
AnythingLLM uses different .env files depending on the deployment method and application component:
File Locations:
| Component | Development | Production | Docker |
|---|---|---|---|
| Server | server/.env.development | server/.env | docker/.env → /app/server/.env |
| Collector | collector/.env | collector/.env | Inherited from server |
| Frontend | frontend/.env | Built into static bundle | N/A |
Sources: server/.env.example1-426 docker/.env.example1-426 server/models/systemSettings.js1-4
Environment variables flow through a structured pipeline from file to application:
Sources: server/utils/helpers/updateENV.js7-830 server/models/systemSettings.js209-321
AnythingLLM's environment variables are organized into distinct functional categories:
| Category | Variable Prefix | Count | Primary Purpose |
|---|---|---|---|
| LLM Providers | LLM_PROVIDER, Provider-specific | ~150 | Configure chat completion engines |
| Embedding Engines | EMBEDDING_ENGINE, EMBEDDING_* | ~20 | Configure text embedding models |
| Vector Databases | VECTOR_DB, DB-specific | ~25 | Configure vector storage backends |
| Transcription | WHISPER_PROVIDER, WHISPER_* | ~3 | Audio transcription services |
| TTS/STT | TTS_PROVIDER, TTS_* | ~10 | Text-to-speech and speech-to-text |
| Authentication | AUTH_TOKEN, JWT_SECRET | ~3 | Security and access control |
| Agent Services | AGENT_* | ~15 | Web search and tool integrations |
| System Settings | STORAGE_DIR, SERVER_PORT | ~10 | Core system configuration |
Sources: server/.env.example1-426 server/utils/helpers/updateENV.js7-830
The LLM_PROVIDER variable determines which Large Language Model service to use:
Each LLM provider requires specific configuration variables. Here are examples for major providers:
OpenAI:
Azure OpenAI:
Anthropic:
Ollama (Self-Hosted):
Generic OpenAI (API Proxy):
Sources: server/.env.example8-178 server/utils/helpers/updateENV.js8-830
For Docker deployments, URLs pointing to localhost or 127.0.0.1 undergo special validation via validDockerizedUrl():
This prevents configuration errors where services running on the host machine are unreachable from inside the Docker container.
Sources: server/utils/helpers/updateENV.js1024-1047
The EMBEDDING_ENGINE variable controls which service generates text embeddings for document vectorization:
The native embedder runs locally using Transformers.js and requires no API keys:
Available Models:
Xenova/all-MiniLM-L6-v2 (default)Xenova/bge-small-en-v1.5Xenova/bge-base-en-v1.5nomic-ai/nomic-embed-text-v1.5Changing embedding configuration triggers automatic vector store reset via postUpdate hooks:
This prevents mixing embeddings from different models, which would corrupt similarity search results.
Sources: server/utils/helpers/updateENV.js292-305 server/utils/helpers/updateENV.js1062-1078
OpenAI:
Generic OpenAI (for proxies):
Ollama:
Sources: server/.env.example180-241 server/utils/helpers/updateENV.js292-333
The VECTOR_DB variable determines which vector database stores document embeddings:
LanceDB (Default):
Chroma:
Pinecone:
PGVector (PostgreSQL):
PGVector connections undergo pre-update validation via validatePGVectorConnectionString():
Sources: server/utils/helpers/updateENV.js438-447 server/utils/helpers/updateENV.js1101-1158
Milvus:
Astra DB:
Sources: server/.env.example242-294 server/utils/helpers/updateENV.js336-447
Sources: server/.env.example296-323 server/utils/helpers/updateENV.js533-662
Critical security variables like AUTH_TOKEN and JWT_SECRET require force mode to update via the API:
This prevents accidental security changes through the settings UI.
Sources: server/.env.example325-327 server/utils/helpers/updateENV.js546-552 server/utils/helpers/updateENV.js1020-1022
Agent services enable tools like web search, which the agent system can invoke:
KEY_MAPPING Entries:
Sources: server/.env.example350-384 server/utils/helpers/updateENV.js564-612
Configure password requirements for multi-user mode:
These use the joi-password-complexity library for validation. See server/package.json61 for the dependency.
Sources: server/.env.example329-339 docker/.env.example331-339
Sources: server/.env.example325-421 docker/.env.example325-407
Sources: server/.env.example394-398
These control file ownership in mounted volumes. The Docker image creates an anythingllm user with these IDs.
URLs in Docker must account for container networking:
The validDockerizedUrl() function enforces this automatically.
Sources: docker/.env.example1-7 docker/Dockerfile40-46 docker/Dockerfile109-115
Sources: server/utils/helpers/updateENV.js1164-1220 server/models/systemSettings.js1-4 server/models/systemSettings.js209-321
When settings are updated in production, they're persisted to the .env file:
Protected Keys List:
KEY_MAPPINGJWT_EXPIRY, STORAGE_DIR, SERVER_PORTSIG_KEY, SIG_SALT (encryption)PASSWORDMINCHAR, PASSWORDMAXCHAR, etc. (password schema)ENABLE_HTTPS, HTTPS_CERT_PATH, HTTPS_KEY_PATHDISABLE_VIEW_CHAT_HISTORYSIMPLE_SSO_ENABLED, SIMPLE_SSO_NO_LOGIN, SIMPLE_SSO_NO_LOGIN_REDIRECTCOMMUNITY_HUB_BUNDLE_DOWNLOADS_ENABLEDTARGET_OCR_LANGCOLLECTOR_ALLOW_ANY_IPSources: server/utils/helpers/updateENV.js1244-1332
The updateENV.js file defines numerous validation functions used in KEY_MAPPING:
| Function | Purpose | Example Error |
|---|---|---|
isNotEmpty | Ensures value is not empty | "Value cannot be empty" |
nonZero | Must be number > 0 | "Value must be greater than zero" |
isInteger | Must be whole number | "Value must be a number" |
isValidURL | Valid URL format | "URL is not a valid URL." |
| Function | Purpose | Valid Format |
|---|---|---|
validOpenAIKey | OpenAI key format | Must start with sk- |
validAnthropicApiKey | Anthropic key format | Must start with sk-ant- |
validLLMExternalBasePath | External LLM URL | Must include /v1, no trailing slash |
validOllamaLLMBasePath | Ollama URL | No trailing slash |
validChromaURL | Chroma endpoint | No trailing slash |
validHuggingFaceEndpoint | HuggingFace URL | Must end in .cloud |
| Function | Purpose | Details |
|---|---|---|
supportedLLM | Whitelist check | 46 supported providers |
supportedEmbeddingModel | Whitelist check | 14 supported engines |
supportedVectorDB | Whitelist check | 10 supported databases |
supportedTTSProvider | Whitelist check | 5 TTS providers |
supportedTranscriptionProvider | Whitelist check | 2 transcription providers |
validGeminiSafetySetting | Enum check | BLOCK_NONE, BLOCK_ONLY_HIGH, etc. |
validDockerizedUrl | Port availability | Checks port reachability in Docker |
looksLikePostgresConnectionString | Format check | Must start with postgresql:// |
Sources: server/utils/helpers/updateENV.js832-1006
Sources: server/.env.example1-426 docker/.env.example1-426
Beyond .env files, configuration can be stored in:
For details on how the database and environment variables interact, see System Settings Architecture.
Refresh this wiki