~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Configuring Local Deep Research with Environment Variables
Note: For most users, the Web UI Settings is the recommended way to configure Local Deep Research. Environment variables are primarily useful for Docker deployments, CI/CD pipelines, and server configurations where the web UI is not accessible during startup.
For a complete auto-generated reference of all settings, defaults, and environment variables, see CONFIGURATION.md.
You can override any configuration setting in Local Deep Research using environment variables. This is useful for:
- Setting up multiple environments (development, production)
- Changing settings without modifying configuration files
- Providing sensitive information like API keys securely
- Setting server ports for Docker or cloud deployments
Environment Variable Format
To override a setting, convert its key to uppercase, replace dots with underscores, and prefix with LDR_:
setting.key.name → LDR_SETTING_KEY_NAME
For example:
app.debug→LDR_APP_DEBUGllm.model→LDR_LLM_MODELsearch.tool→LDR_SEARCH_TOOL
Important: Environment variables override UI settings and lock them — the setting becomes read-only in the UI until the environment variable is removed. For settings you may want to adjust later, use the Web UI instead.
Note on empty values: Empty environment variables (e.g.,
LDR_LLM_PROVIDER="") are treated as not set — they will not override anything and the setting remains editable in the UI. This is by design: deployment tools like Unraid and Docker Compose templates often create all environment variables even when fields are left blank. Only non-empty values act as overrides. To remove an override, delete the environment variable entirely rather than setting it to an empty string.Per-run overrides: When starting research via the API or web UI, explicit per-run parameters (
max_results,iterations,questions_per_iteration,strategy) take precedence over both database settings and environment variable overrides for that specific run.time_periodfollows one order on every path, because environment values are operator policy: atime_periodpassed in code, then a per-engine variable such asLDR_SEARCH_ENGINE_WEB_SERPAPI_DEFAULT_PARAMS_TIME_PERIOD, thenLDR_SEARCH_TIME_PERIOD, then a per-runtime_period, then the engine's own choice saved in Settings, then the saved Search → Time Period (allif none is set). SoLDR_SEARCH_TIME_PERIODalso outranks a period saved for a single engine, with or without a per-run value. Environment variables still lock the stored setting and UI; the per-run exception applies only to the explicit request payload, not to persisted configuration.
For the complete list of all settings, their environment variable names, and default values, see CONFIGURATION.md.
Invalid setting values
Settings-manager reads and effective snapshots raise SettingsValueError when
the selected value cannot be converted or its setting type is unsupported.
For example, LDR_SEARCH_ITERATIONS=invalid stops the operation instead of
using the saved iteration count or a default. Correct or remove the invalid
override before retrying. An invalid stored value also fails when it is the
selected value; a valid environment override still takes precedence. A
variable for a key with no declared setting type and no saved row, such as
LDR_APP_API_RATE_LIMIT or LDR_APP_ENABLE_API, has nothing to be validated
against: it is read as the raw string, and the code that uses it parses it.
Numeric values must be finite numbers, not booleans. Environment overrides
for boolean settings accept true, 1, yes, on, enabled and their false counterparts
false, 0, no, off, disabled, ignoring case and surrounding whitespace.
JSON environment overrides must contain valid JSON. Errors identify the
setting and source without including the configured value.
Absent optional settings still use their documented defaults. Empty overrides
for database-backed settings retain the unset behavior described above.
Environment-only integer settings also treat empty or whitespace-only values
as unset, including the trusted-proxy count. Other malformed integer values
still raise a settings error on managed reads. Environment-only boolean
settings differ: an empty or whitespace-only value reads as false, not as
unset, so LDR_NEWS_SCHEDULER_ENABLED="" disables a default-on setting.
The raw export API (include_environment_overrides=False) preserves stored
values and metadata so invalid configuration can be inspected and repaired.
A screen or API endpoint that loads a full effective snapshot will fail if any
entry in that snapshot is invalid, even when the requested field is different.
Getting Variables Into LDR (and Making Them Persistent)
LDR's own code never loads a .env file into its settings — it reads
only the environment of the server process. Two things can still involve a
.env file, neither of which is LDR loading one for its settings:
- Rate limiting: the bundled
slowapilibrary reads its ownRATELIMIT_*keys from a.envfile in the server's working directory, and LDR looks up the legacy rate-limit storage URL key there the same way, only to report and redact it. - A dependency can put a stray
.envfile's keys into the process environment, where LDR then reads them like any other variable (see the caveat below).
The bundled .env.template is a reference of available names, not a
file LDR opens by itself. Keeping your values in a file is still perfectly
fine: hand the file to whatever starts LDR rather than to
LDR — docker run --env-file <file>, Compose env_file:, or systemd
EnvironmentFile= all read a key=value file and put its contents into the
process environment, which is what LDR then sees.
The export examples on this page are ephemeral: they last until the shell
session ends. To make a variable survive restarts and reboots, use the
mechanism that matches your deployment:
| Deployment | Persistent mechanism |
|---|---|
| Docker Compose | Add the variable under the service's environment: section in docker-compose.yml (this is how the bundled compose file sets the SearXNG URL), or point the service's env_file: at a key=value file |
docker run |
Pass -e NAME=value in the run command, or --env-file <file> to load a whole key=value file (persist either in whatever script/systemd unit starts the container) |
| pip + systemd | Add Environment="NAME=value" lines to the unit, or point EnvironmentFile= at a root-owned key=value file |
| pip + manual shell | Add the export lines to your shell profile (~/.bashrc or similar), or prefix the launch command: NAME=value ldr-web |
| Unraid | Add the variable as a field on the container template |
After changing a variable, restart LDR — values are read at startup (and on each settings lookup from the live environment, but a restart is the reliable way to guarantee every subsystem sees the change).
Caveat: a dependency may pull in a stray .env (pip installs)
One of LDR's own dependencies, crawl4ai (imported on the library
document-download path), calls load_dotenv() at import time — the bare
call at the top of crawl4ai/config.py, verified against crawl4ai 0.9.2.
Because that call passes no arguments, python-dotenv's find_dotenv() runs
with usecwd=False, which searches upward from the calling file rather
than from the working directory. The calling file is config.py inside
site-packages, so on a pip install the walk goes up through the virtualenv
and into its parents: a .env sitting next to .venv/ — typically your
project directory — can be read at that moment and its keys added to the
process environment.
Any LDR_* names in such a file then behave exactly like variables you set
deliberately: environment values win over UI settings and lock the
corresponding fields in the settings UI. Real variables already exported in
the environment are not overwritten.
The one exception to the search path is that find_dotenv() falls back to
the current working directory when it detects a REPL, a notebook, a debugger
or a frozen build. In python-dotenv 1.2.3 (the version pdm.lock resolves)
that condition is
usecwd or _is_interactive() or _is_debugger() or getattr(sys, "frozen", False),
where _is_debugger() is sys.gettrace() is not None. The debugger clause
is newer than the other three, so an older python-dotenv will not have it.
Under a debugger, then, the file picked up is the one near your CWD instead
— worth knowing if you are trying to reproduce this deliberately and the
parent-directory .env appears to be ignored.
This is not a supported way to configure LDR — it is a side effect worth
knowing about if a setting mysteriously refuses to change in the UI.
Container installs are unaffected in practice: the virtualenv lives at
/install/.venv, so the walk only reaches /install/ and / — neither of
which is user-writable or mounted from the host in the bundled image — and
never a user's data directory. If you hit it, remove
or rename the stray .env, or move the virtualenv out from under it.
API Keys
API keys are best set using environment variables for security. Only the LDR_ prefixed version is needed.
Security note: Setting an API key variable to an empty string (e.g.,
LDR_LLM_OPENAI_API_KEY="") does not block or clear the key — it is treated as unset, and the key remains editable in the UI. If a key is already stored in the database, it will still be used. To explicitly block a stored API key, set its variable to a non-empty placeholder that is not a working key (e.g.,DISABLED). API keys are plain-text settings, so the placeholder replaces the stored key without a settings error. This does not work for typed settings such as numbers, checkboxes or JSON: a value that cannot be converted raises a settings error (see Invalid setting values).
# LLM API keys
export LDR_LLM_OPENAI_API_KEY=your-openai-key-here
export LDR_LLM_ANTHROPIC_API_KEY=your-anthropic-key-here
export LDR_LLM_OPENROUTER_API_KEY=your-openrouter-key-here
# Search engine API keys
export LDR_SEARCH_ENGINE_WEB_BRAVE_API_KEY=your-brave-key-here
export LDR_SEARCH_ENGINE_WEB_SERPAPI_API_KEY=your-serpapi-key-here
export LDR_SEARCH_ENGINE_WEB_TAVILY_API_KEY=your-tavily-key-here
For the full list of API key environment variables, see CONFIGURATION.md.
LLM Provider Configuration
OpenRouter
OpenRouter provides access to 100+ models through an OpenAI-compatible API. To use OpenRouter:
- Get an API key from openrouter.ai
- Configure using one of these methods:
Method 1: Via Web UI (Recommended)
- Navigate to Settings → LLM Provider
- Select "OpenAI-Compatible Endpoint"
- Set Endpoint URL to:
https://openrouter.ai/api/v1 - Enter your OpenRouter API key
- Select your desired model
Method 2: Via Environment Variables
# Required environment variables for OpenRouter
export LDR_LLM_PROVIDER=openai_endpoint
export LDR_LLM_OPENAI_ENDPOINT_URL=https://openrouter.ai/api/v1
export LDR_LLM_OPENAI_ENDPOINT_API_KEY="<your-api-key>"
export LDR_LLM_MODEL=anthropic/claude-3.5-sonnet # or any OpenRouter model
Method 3: Docker Compose
Add to your docker-compose.yml environment section:
services:
local-deep-research:
environment:
- LDR_LLM_PROVIDER=openai_endpoint
- LDR_LLM_OPENAI_ENDPOINT_URL=https://openrouter.ai/api/v1
- LDR_LLM_OPENAI_ENDPOINT_API_KEY=<your-api-key>
- LDR_LLM_MODEL=anthropic/claude-3.5-sonnet
Available Models: Browse models at openrouter.ai/models
Note: OpenRouter uses the OpenAI-compatible API, so you select "OpenAI-Compatible Endpoint" as the provider and change the endpoint URL to OpenRouter's API.
Other OpenAI-Compatible Providers
The same configuration pattern works for any OpenAI-compatible API service:
# Generic pattern for OpenAI-compatible APIs
export LDR_LLM_PROVIDER=openai_endpoint
export LDR_LLM_OPENAI_ENDPOINT_URL=https://your-provider.com/v1
export LDR_LLM_OPENAI_ENDPOINT_API_KEY="<your-api-key>"
export LDR_LLM_MODEL="<your-model-name>"
Docker Usage
For Docker deployments, you can pass environment variables when starting containers:
docker run -p 5000:5000 \
-e LDR_LLM_OPENAI_API_KEY=your-api-key-here \
-e LDR_SEARCH_TOOL=wikipedia \
local-deep-research
Migrating from server_config.json
The server_config.json file is deprecated and will be removed in a future release. Migrate your settings to environment variables using this mapping:
| server_config.json key | Environment Variable |
|---|---|
host |
LDR_WEB_HOST |
port |
LDR_WEB_PORT |
debug |
LDR_APP_DEBUG |
use_https |
LDR_WEB_USE_HTTPS |
allow_registrations |
LDR_APP_ALLOW_REGISTRATIONS |
rate_limit_default |
LDR_SECURITY_RATE_LIMIT_DEFAULT |
rate_limit_login |
LDR_SECURITY_RATE_LIMIT_LOGIN |
rate_limit_registration |
LDR_SECURITY_RATE_LIMIT_REGISTRATION |
rate_limit_settings |
LDR_SECURITY_RATE_LIMIT_SETTINGS |
After setting the environment variables, delete server_config.json from your data directory. The web UI will show a warning banner while the file still exists.
Common Operations
Changing the Web Port
export LDR_WEB_PORT=8080 # Linux/Mac
set LDR_WEB_PORT=8080 # Windows
Note:
LDR_APP_PORTis a separate setting for notification URL generation. To change the port the server listens on, useLDR_WEB_PORT. Requires server restart.
Setting API Keys
# Linux/Mac
export LDR_LLM_ANTHROPIC_API_KEY=your-api-key-here
# Windows
set LDR_LLM_ANTHROPIC_API_KEY=your-api-key-here
Changing Search Engine
export LDR_SEARCH_TOOL=wikipedia # Linux/Mac
set LDR_SEARCH_TOOL=wikipedia # Windows
Data Directory Location
By default, Local Deep Research stores all data (database, research outputs, cache, logs) in platform-specific user directories. You can override this location using the LDR_DATA_DIR environment variable:
# Linux/Mac
export LDR_DATA_DIR=/path/to/your/data/directory
# Windows
set LDR_DATA_DIR=C:\path\to\your\data\directory
All application data will be organized under this directory:
$LDR_DATA_DIR/ldr.db- Application database$LDR_DATA_DIR/research_outputs/- Research reports$LDR_DATA_DIR/cache/- Cached data$LDR_DATA_DIR/logs/- Application logs
Removed Bootstrap Variables
The following variables were previously listed in the configuration reference but did not change the behavior they described. They have been removed from the environment-setting registry:
LDR_BOOTSTRAP_ENCRYPTION_KEYLDR_BOOTSTRAP_SECRET_KEYLDR_BOOTSTRAP_DATABASE_URLLDR_BOOTSTRAP_DATA_DIRLDR_BOOTSTRAP_CONFIG_DIRLDR_BOOTSTRAP_LOG_DIRLDR_BOOTSTRAP_ENABLE_FILE_LOGGING
User databases use password-derived encryption keys. The session-signing key is persisted in .secret_key inside the data directory. Use LDR_DATA_DIR to choose that directory and LDR_ENABLE_FILE_LOGGING=true to enable file logging (only the word true, in any letter case, enables it; 1 and yes do not). These existing mechanisms are unchanged.
Debug Logging (LDR_APP_DEBUG and LDR_LOGURU_DIAGNOSE)
LDR_APP_DEBUG=true raises the log level to DEBUG for more informative output. It does not, on its own, enable Loguru's diagnose mode, which renders the repr() of every local variable in every traceback frame on exceptions and can materialise credentials (API keys, the SQLCipher master password, Authorization headers) into your logs.
To opt into that variable-level detail, set LDR_LOGURU_DIAGNOSE=true in addition to LDR_APP_DEBUG=true. Keep it disabled in production; a warning is emitted whenever it is active.
# Verbose logs, no local-variable dumps (safe default for debugging)
export LDR_APP_DEBUG=true
# Full exception diagnostics including frame locals (NEVER in production)
export LDR_APP_DEBUG=true
export LDR_LOGURU_DIAGNOSE=true
Database Configuration (SQLCipher)
Database encryption settings are configured exclusively via environment variables (they cannot be changed through the Web UI). These settings are applied at database creation time and must remain consistent for the database to be accessible.
For the full list of database configuration variables, defaults, constraints, and deprecated aliases, see the Pre-Database (Env-Only) Settings section in CONFIGURATION.md.
Upload Size Limit
The per-file upload cap is read from LDR_SECURITY_UPLOAD_MAX_FILE_SIZE_MB at startup. The value is in megabytes; the default is 3072 MB (3 GB). Values must be positive integers; zero, negative, or non-integer values fall back to the default with a warning.
# Allow up to 5 GB per file
export LDR_SECURITY_UPLOAD_MAX_FILE_SIZE_MB=5120
# Tighten to 100 MB
export LDR_SECURITY_UPLOAD_MAX_FILE_SIZE_MB=100
This cap applies to both the research-upload and RAG-collection upload endpoints. A separate library-side setting (research_library.max_pdf_size_mb) controls whether a PDF that passes the upload cap can also be stored in the library — both default to 3 GB and should typically be raised or lowered together.
Memory usage stays bounded regardless of the cap: multipart uploads are spooled to disk above a 5 MB threshold (DiskSpoolingRequest.max_form_memory_size), so the per-file cap does not directly affect RAM consumption.
Requires a server restart to take effect.
CORS / WebSocket Security
These settings control Cross-Origin Resource Sharing (CORS) for API routes and WebSocket connections. For the full list of security environment variables and their defaults, see CONFIGURATION.md.
WebSocket connections also require an authenticated session in addition to passing the CORS check below. The CORS setting controls which origins may attempt a handshake; the auth requirement ensures only logged-in users can complete one.
Values:
*— Allow all origins (most permissive)- Empty string or unset — Same-origin only (most restrictive)
- Comma-separated list — Allow specific origins only
Examples:
# Same-origin only (the default — leave both unset, shown here for clarity)
export LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS=""
# Allow specific cross-origin front-ends (recommended when you need cross-origin)
export LDR_SECURITY_CORS_ALLOWED_ORIGINS="https://example.com,https://app.example.com"
export LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS="https://example.com,https://app.example.com"
# Allow ALL origins — disables CORS/WebSocket origin checks.
# Trusted local/dev networks only; do not use in production.
export LDR_SECURITY_CORS_ALLOWED_ORIGINS="*"
export LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS="*"
Docker Compose example:
services:
local-deep-research:
environment:
# Same-origin is the secure default — omit these unless you serve the UI
# from a different origin, then list it explicitly (avoid "*").
- LDR_SECURITY_CORS_ALLOWED_ORIGINS=https://app.example.com
- LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS=https://app.example.com
Note: If WebSocket connections fail after upgrading to the same-origin default, the usual cause is a TLS-terminating reverse proxy that doesn't forward X-Forwarded-Proto (see the Socket.IO proxy snippet in troubleshooting — the same header is needed for secure cookies/HSTS). Otherwise, set LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS to your front-end origin (e.g. https://app.example.com); a fully cross-origin front-end must also set LDR_SECURITY_CORS_ALLOWED_ORIGINS. Using * re-enables allow-all and is not recommended outside trusted local/dev networks.