# 1535 Env Configuration C9f846e2

> Configuring Local Deep Research with Environment Variables

- Skill: `tools-only/1535-env-configuration-c9f846e2` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/1535-env-configuration-c9f846e2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/1535-env-configuration-c9f846e2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tools-only/1535-env-configuration-c9f846e2

---

# 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](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

Local Deep Research uses Dynaconf to manage configuration. The format for environment variables is:

```
LDR_SECTION__SETTING=value
```

Note the **double underscore** (`__`) between the section and setting name.

## Using .env Files in the Config Directory

The easiest way to configure settings is to create a `.env` file in your config directory:

**Config Directory Locations:**
- Windows: `%USERPROFILE%\Documents\LearningCircuit\local-deep-research\config\.env`
- Linux/Mac: `~/.config/local_deep_research/config/.env`

Simply create a text file named `.env` in this directory and add your settings:

```
# Example .env file contents
LDR_WEB__PORT=8080
LDR_SEARCH__TOOL=wikipedia
LDR_GENERAL__ENABLE_FACT_CHECKING=true

# API keys (see important note below)
OPENAI_API_KEY=your-key-here
LDR_OPENAI_API_KEY=your-key-here
```

This file is automatically loaded when Local Deep Research starts, and any settings specified here will override those in the main configuration files.

## Important Note About API Keys

**Known Bug**: Currently, API keys must be set **both with and without** the `LDR_` prefix for search engines to work properly:

```bash
# You need BOTH of these for each API key
export OPENAI_API_KEY=your-key-here
export LDR_OPENAI_API_KEY=your-key-here
```

This applies to all search-related API keys including:
- `OPENAI_API_KEY`
- `ANTHROPIC_API_KEY`
- `SERP_API_KEY`
- `BRAVE_API_KEY`
- `GOOGLE_PSE_API_KEY`
- `GOOGLE_PSE_ENGINE_ID`
- `GUARDIAN_API_KEY`

This issue will be fixed in a future update.

## Examples

| Config in settings.toml | Environment Variable | Example |
|-------------------------|----------------------|---------|
| `[web]` port = 5000 | `LDR_WEB__PORT` | `LDR_WEB__PORT=8080` |
| `[search]` tool = "auto" | `LDR_SEARCH__TOOL` | `LDR_SEARCH__TOOL=wikipedia` |
| `[general]` enable_fact_checking = false | `LDR_GENERAL__ENABLE_FACT_CHECKING` | `LDR_GENERAL__ENABLE_FACT_CHECKING=true` |

## API Keys

API keys are best set using environment variables for security (remember the current requirement for both prefixed and non-prefixed versions):

```bash
# Set both versions for each API key
ANTHROPIC_API_KEY=your-api-key-here
LDR_ANTHROPIC_API_KEY=your-api-key-here

OPENAI_API_KEY=your-openai-key-here
LDR_OPENAI_API_KEY=your-openai-key-here

SERP_API_KEY=your-api-key-here
LDR_SERP_API_KEY=your-api-key-here
```

## LLM Provider Configuration

### OpenRouter

[OpenRouter](https://openrouter.ai/) provides access to 100+ models through an OpenAI-compatible API. To use OpenRouter:

1. Get an API key from [openrouter.ai](https://openrouter.ai/)
2. Configure using one of these methods:

**Method 1: Via Web UI (Recommended)**
- Navigate to Settings → LLM Provider
- Select "Custom OpenAI Endpoint"
- Set Endpoint URL to: `https://openrouter.ai/api/v1`
- Enter your OpenRouter API key
- Select your desired model

**Method 2: Via Environment Variables**

```bash
# 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:

```yaml
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](https://openrouter.ai/models)

**Note**: OpenRouter uses the OpenAI-compatible API, so you select "Custom OpenAI 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:

```bash
# 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:

```bash
docker run -p 8080:8080 \
  -e LDR_WEB__PORT=8080 \
  -e LDR_SEARCH__TOOL=wikipedia \
  -e OPENAI_API_KEY=your-key-here \
  -e LDR_OPENAI_API_KEY=your-key-here \
  local-deep-research
```

## Common Operations

### Changing the Web Port

```bash
export LDR_WEB__PORT=8080  # Linux/Mac
set LDR_WEB__PORT=8080     # Windows
```

### Setting API Keys (with current dual requirement)

```bash
# Linux/Mac
export ANTHROPIC_API_KEY=your-key-here
export LDR_ANTHROPIC_API_KEY=your-key-here

# Windows
set ANTHROPIC_API_KEY=your-key-here
set LDR_ANTHROPIC_API_KEY=your-key-here
```

### Changing Search Engine

```bash
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:

```bash
# 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

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

| Setting | Canonical Env Var | Default |
|---------|-------------------|---------|
| KDF iterations | `LDR_DB_CONFIG_KDF_ITERATIONS` | `256000` |
| Page size | `LDR_DB_CONFIG_PAGE_SIZE` | `16384` |
| HMAC algorithm | `LDR_DB_CONFIG_HMAC_ALGORITHM` | `HMAC_SHA512` |
| KDF algorithm | `LDR_DB_CONFIG_KDF_ALGORITHM` | `PBKDF2_HMAC_SHA512` |
| Cache size (MB) | `LDR_DB_CONFIG_CACHE_SIZE_MB` | `64` |
| Journal mode | `LDR_DB_CONFIG_JOURNAL_MODE` | `WAL` |
| Synchronous mode | `LDR_DB_CONFIG_SYNCHRONOUS` | `NORMAL` |
| Allow unencrypted DB | `LDR_BOOTSTRAP_ALLOW_UNENCRYPTED` | `false` |

**Deprecated names:** The following older env var names still work but will be removed in a future release. If you are using them, please migrate to the canonical names above:

| Deprecated Name | Canonical Replacement |
|-----------------|----------------------|
| `LDR_DB_KDF_ITERATIONS` | `LDR_DB_CONFIG_KDF_ITERATIONS` |
| `LDR_DB_PAGE_SIZE` | `LDR_DB_CONFIG_PAGE_SIZE` |
| `LDR_DB_HMAC_ALGORITHM` | `LDR_DB_CONFIG_HMAC_ALGORITHM` |
| `LDR_DB_KDF_ALGORITHM` | `LDR_DB_CONFIG_KDF_ALGORITHM` |
| `LDR_DB_CACHE_SIZE_MB` | `LDR_DB_CONFIG_CACHE_SIZE_MB` |
| `LDR_DB_JOURNAL_MODE` | `LDR_DB_CONFIG_JOURNAL_MODE` |
| `LDR_DB_SYNCHRONOUS` | `LDR_DB_CONFIG_SYNCHRONOUS` |
| `LDR_ALLOW_UNENCRYPTED` | `LDR_BOOTSTRAP_ALLOW_UNENCRYPTED` |

A deprecation warning is logged when a deprecated name is used. If both canonical and deprecated names are set, the canonical name takes precedence.

### CORS / WebSocket Security

These settings control Cross-Origin Resource Sharing (CORS) for API routes and WebSocket connections. By default, API CORS is restricted to same-origin, and WebSocket allows all origins for broad compatibility.

| Setting | Env Var | Default | Description |
|---------|---------|---------|-------------|
| API CORS origins | `LDR_SECURITY_CORS_ALLOWED_ORIGINS` | `""` (same-origin) | Allowed origins for API routes |
| WebSocket origins | `LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS` | `"*"` (all origins) | Allowed origins for Socket.IO connections |

**Values:**
- `*` — Allow all origins (most permissive)
- Empty string or unset — Same-origin only (most restrictive)
- Comma-separated list — Allow specific origins only

**Examples:**

```bash
# Allow all origins for both API and WebSocket
export LDR_SECURITY_CORS_ALLOWED_ORIGINS="*"
export LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS="*"

# Restrict to specific origins
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"

# Same-origin only (strictest)
export LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS=""
```

**Docker Compose example:**

```yaml
services:
  local-deep-research:
    environment:
      - LDR_SECURITY_CORS_ALLOWED_ORIGINS=*
      - LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS=*
```

**Note:** If WebSocket connections fail after upgrading, set `LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS=*` to restore the previous permissive behavior.