Skip to content

~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.

19.9 KB
Raw Blame

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_DEBUG
  • llm.model → LDR_LLM_MODEL
  • search.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_period follows one order on every path, because environment values are operator policy: a time_period passed in code, then a per-engine variable such as LDR_SEARCH_ENGINE_WEB_SERPAPI_DEFAULT_PARAMS_TIME_PERIOD, then LDR_SEARCH_TIME_PERIOD, then a per-run time_period, then the engine's own choice saved in Settings, then the saved Search → Time Period (all if none is set). So LDR_SEARCH_TIME_PERIOD also 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 slowapi library reads its own RATELIMIT_* keys from a .env file 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 .env file'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:

  1. Get an API key from openrouter.ai
  2. 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_PORT is a separate setting for notification URL generation. To change the port the server listens on, use LDR_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_KEY
  • LDR_BOOTSTRAP_SECRET_KEY
  • LDR_BOOTSTRAP_DATABASE_URL
  • LDR_BOOTSTRAP_DATA_DIR
  • LDR_BOOTSTRAP_CONFIG_DIR
  • LDR_BOOTSTRAP_LOG_DIR
  • LDR_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.