~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.
Migration Guide: LDR v0.x to v1.0
Overview
Local Deep Research v1.0 introduces significant security and architectural improvements:
- User Authentication: All access now requires authentication
- Per-User Encrypted Databases: Each user has their own encrypted SQLCipher database
- Settings Snapshots: Thread-safe settings management for concurrent operations
- New API Structure: Reorganized endpoints under router prefixes
Breaking Changes
1. Authentication Required
v0.x: Open access, no authentication
# Direct API access
from local_deep_research.api import quick_summary
result = quick_summary("query")
v1.0: Authentication required
from local_deep_research.api import quick_summary
from local_deep_research.settings import SettingsManager
from local_deep_research.database.session_context import get_user_db_session
# Must authenticate first
with get_user_db_session(username="user", password="pass") as session:
settings_manager = SettingsManager(session)
settings_snapshot = settings_manager.get_all_settings()
result = quick_summary(
"query",
settings_snapshot=settings_snapshot # Required parameter
)
2. HTTP API Changes
Endpoint Structure
- v0.x:
/api/v1/quick_summary - v1.0:
/api/start_research
Authentication Flow
import requests
# v1.0 requires session-based authentication
session = requests.Session()
# 1. Login
session.post(
"http://localhost:5000/auth/login",
json={"username": "user", "password": "pass"}
)
# 2. Get CSRF token for state-changing operations
csrf = session.get("http://localhost:5000/auth/csrf-token").json()["csrf_token"]
# 3. Make API requests with CSRF token
response = session.post(
"http://localhost:5000/api/start_research",
json={"query": "test"},
headers={"X-CSRF-Token": csrf}
)
3. Database Changes
v0.x
- Single shared database:
ldr.db - No encryption
- Direct database access from any thread
v1.0
- Per-user databases:
encrypted_databases/{username}.db - SQLCipher encryption with user passwords
- Thread-local session management
- In-memory queue tracking (no more service_db)
4. Settings Management
v0.x
# Direct settings access
from local_deep_research.config import get_db_setting
value = get_db_setting("llm.provider")
v1.0
# Settings require context
from local_deep_research.settings import SettingsManager
# Within authenticated session
settings_manager = SettingsManager(session)
value = settings_manager.get_setting("llm.provider")
# Or use settings snapshot for thread safety
settings_snapshot = settings_manager.get_all_settings()
Migration Steps
1. Update Dependencies
pip install --upgrade local-deep-research
2. Create User Accounts
Users must create accounts through the web interface:
- Start the server:
python -m local_deep_research.web.app - Open http://localhost:5000
- Click "Register" and create an account
- Configure LLM providers and API keys in Settings
3. Update Programmatic Code
Before (v0.x):
from local_deep_research.api import (
quick_summary,
detailed_research,
generate_report
)
# Direct usage
result = quick_summary("What is AI?")
After (v1.0):
from local_deep_research.api import quick_summary
from local_deep_research.settings import SettingsManager
from local_deep_research.database.session_context import get_user_db_session
def run_research(username, password, query):
with get_user_db_session(username, password) as session:
settings_manager = SettingsManager(session)
settings_snapshot = settings_manager.get_all_settings()
return quick_summary(
query=query,
settings_snapshot=settings_snapshot,
# Other parameters remain the same
iterations=2,
questions_per_iteration=3
)
4. Update HTTP API Calls
Create a wrapper for authenticated requests:
class LDRClient:
def __init__(self, base_url="http://localhost:5000"):
self.base_url = base_url
self.session = requests.Session()
self.csrf_token = None
def login(self, username, password):
response = self.session.post(
f"{self.base_url}/auth/login",
json={"username": username, "password": password}
)
if response.status_code == 200:
self.csrf_token = self.session.get(
f"{self.base_url}/auth/csrf-token"
).json()["csrf_token"]
return response
def start_research(self, query, **kwargs):
return self.session.post(
f"{self.base_url}/api/start_research",
json={"query": query, **kwargs},
headers={"X-CSRF-Token": self.csrf_token}
)
# Usage
client = LDRClient()
client.login("user", "pass")
result = client.start_research("What is quantum computing?")
5. Update Configuration
API Keys
API keys are now stored encrypted in per-user databases. Users must:
- Login to the web interface
- Go to Settings
- Re-enter API keys for LLM providers
Custom LLMs
Custom LLM registrations now require settings context:
# v1.0 custom LLM with settings support
def create_custom_llm(model_name=None, temperature=None, settings_snapshot=None):
# Access settings from snapshot if needed
api_key = settings_snapshot.get("llm.custom.api_key", {}).get("value")
return CustomLLM(api_key=api_key, model=model_name, temperature=temperature)
Common Issues and Solutions
Issue: "No settings context available in thread"
Solution: Pass settings_snapshot parameter to all API calls
Issue: "Encrypted database requires password"
Solution: Ensure you're using get_user_db_session() with credentials
Issue: CSRF token errors
Solution: Get fresh CSRF token before state-changing requests
Issue: Old endpoints return 404
Solution: Update to new endpoint structure (see mapping above)
Issue: Rate limiting not working
Solution: Rate limits are now per-user; ensure proper authentication
Backward Compatibility
For temporary backward compatibility, you can:
- Set environment variable:
LDR_USE_SHARED_DB=1(not recommended) - Create a compatibility wrapper for your existing code
# compatibility.py
import os
os.environ["LDR_USE_SHARED_DB"] = "1" # Use at your own risk
def quick_summary_compat(query, **kwargs):
# Minimal compatibility wrapper
# Note: This bypasses security features!
from local_deep_research.api import quick_summary
return quick_summary(query, settings_snapshot={}, **kwargs)
⚠️ Warning: Compatibility mode bypasses security features and is not recommended for production use.
Benefits of v1.0
- Security: Encrypted databases protect sensitive API keys and research data
- Multi-User: Multiple users can work simultaneously without conflicts
- Performance: Cached settings and thread-local sessions improve speed
- Reliability: Thread-safe operations prevent race conditions
- Privacy: User data is completely isolated
Upgrading to the FastAPI-based Release (Phase 1)
The server has migrated from Flask + Werkzeug to FastAPI + uvicorn.
The sections below highlight the changes most likely to affect an interactive
user. They are not the complete operator checklist, and several are permanent
contract changes rather than one-time upgrade effects. Before upgrading, read
the upgrade and rollback guide for the backup,
verification and rollback procedure, and
changelog.d/3299.breaking.md for the full
list and client/API migration details.
You will need to log in again
Flask and Starlette (FastAPI's session middleware) sign session cookies using different itsdangerous schemes, so the session cookie your browser holds from the Flask version is not readable by the new server. You will be redirected to the login page on first visit and must re-enter your password. Your data is not affected — only the browser session.
Default bind address is now 127.0.0.1
Prior Flask-era releases bound to 0.0.0.0 (all interfaces) by default,
which silently exposed the server to the LAN or public internet. The new
default is 127.0.0.1 (localhost only). To expose the server to other
machines — for example a home server — set the environment variable
LDR_WEB_HOST=0.0.0.0 explicitly. Docker users are unaffected: the
Dockerfile sets this env var automatically so container port mapping
still works.
Reverse proxies must opt in to forwarded request metadata
Set TRUST_PROXY_HEADERS=true when TLS terminates at a trusted reverse proxy.
Without it, uvicorn keeps the request scheme as HTTP, so secure-cookie, HSTS,
and WebSocket same-origin behaviour will be wrong. Client-IP extraction for
rate limiting follows a separate rule, so a single proxy must overwrite
forwarded client-IP headers even when this variable is unset. Behind a chain
of proxies (CDN → nginx) the default settings key every client on the outer
proxy's address, so all clients share one rate-limit bucket: either have the
inner proxy resolve the real client itself (nginx realip) and overwrite
with that address, or make every inner proxy append and set a multi-hop
setting — see Proxy chains. Use
the hardened examples in
Reverse proxy configuration.
With TRUST_PROXY_HEADERS=true, also set LDR_SERVER_FORWARDED_ALLOW_IPS to
your reverse proxy's IP address(es) as LDR sees them — every hop, for a
chain whose inner proxies append. For LDR in Docker behind a proxy on the
host, that is the Docker network's gateway, not 127.0.0.1 (see
Reverse proxy configuration). It defaults to * (every peer, the value
LDR used before), which keeps booting but logs a warning, because a client
that reaches LDR directly can then forge X-Forwarded-For. Two cases need
action:
- Your proxy connects from a public or carrier-grade-NAT address and sends
X-Real-IPwithoutX-Forwarded-For(a cloud load balancer, a Tailscale100.64.x.xpeer, a public nginx host). Without a restrictedLDR_SERVER_FORWARDED_ALLOW_IPS,X-Real-IPis honoured only from a private, loopback or link-local peer; once a restricted list is set, ONLY listed peers are trusted, so list the proxy that connects to LDR even if its address is private (and, for a chain, see Proxy chains). Without that, every client shares one rate-limit bucket and the login and registration lockouts apply to everyone at once. SetLDR_SERVER_FORWARDED_ALLOW_IPSto that proxy's IP address as LDR sees it, or have a single proxy overwriteX-Forwarded-Forwith the address it observed ($remote_addr), never pass a client-sent one through. WithoutTRUST_PROXY_HEADERS, onlyLDR_SERVER_FORWARDED_ALLOW_IPShelps: a public-address proxy'sX-Forwarded-Foris ignored too. - You set
LDR_SERVER_TRUSTED_PROXY_COUNTor an explicitLDR_SERVER_FORWARDED_ALLOW_IPSwhile the allow-list still trusts every peer (*,0.0.0.0/0, ...). LDR refuses to start, because that combination is always exploitable. List your proxy's real IP(s) instead.
The previous behaviour (trusting X-Real-IP from any peer) cannot be turned
back on: it let any client choose its own rate-limit bucket.
The Socket.IO endpoint moved to /ws/socket.io
The Socket.IO server is now an ASGI sub-app mounted at /ws
(app.mount("/ws", socket_app) in web/fastapi_app.py), and it is served
under the path /ws/socket.io (socketio_path="/ws/socket.io" in
web/services/socketio_asgi.py). The bundled UI already connects with
path: '/ws/socket.io'. If you wrote your own Socket.IO client, or if your
reverse proxy has an explicit location block for the old default
/socket.io path, update it — see
Reverse proxy configuration.
WebSocket cross-origin default is unchanged
LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS behaves exactly as before: unset
means same-origin only. Set it explicitly if you need cross-origin WS
access (rare).
An earlier version of this section said the default was "tightened" from
"*" to same-origin. That was wrong — the previous release's
web/services/socket_service.py already fell through to a same-origin
allowlist when the variable was unset. Nothing about origin policy changed
in this migration; only the transport moved.
Session cookies explicitly use SameSite=Lax
Following a top-level link from another site preserves the authenticated session. Cross-site unsafe requests do not carry the cookie, and unsafe methods also require the session CSRF token. That token does not help when a page's own script makes the request, and a link from another site can open any page signed in. So GET routes must not change state, and page-load scripts must not turn URL parameters into state-changing requests.
- Model discovery and refresh require POST; ordinary model-list GET requests only read cached models, including when the cache is empty or expired.
- A
/chat/?q=<text>link no longer sends anything by itself. Earlier versions could send the query and start a research run as soon as the page loaded. Nowqonly pre-fills the chat box of a new chat, or of a chat with no messages yet, without focusing it, and nothing is sent until the user presses Send; an auto-repeated Enter from a key that was already held down does not send. In addition, when the browser'sSec-Fetch-Siteheader says the link came from another origin (cross-siteorsame-site; browsers send the header to HTTPS and localhost origins), the server redirects to the same page withoutq. The login page dropsqfrom a chat page in itsnextparameter, whatever the header says, both in the form it renders and in the redirect after signing in. A typed or bookmarked URL, or a link opened from another app such as a mail or chat client, arrives withSec-Fetch-Site: noneand keepsq, as does any link to a plain-HTTP address other than localhost, where browsers send noSec-Fetch-Site; for a signed-in user such a link pre-fills the chat box. Chat mode on the main page submits its message through the protected API before opening its clean chat URL, so one submit still starts the chat. Queries are not staged in browser storage.
The cookie policy is explicitly set to same_site="lax" where
SessionMiddleware is installed (web/fastapi_app.py); it is not a setting
or environment variable.
Graceful shutdown timeout is bounded (10 s)
uvicorn.run(timeout_graceful_shutdown=10) — in-flight SSE streams are
closed after 10 seconds when the server receives SIGTERM/SIGINT, rather
than blocking indefinitely. This is currently hardcoded — there is no
setting or environment variable to lengthen the drain window. If you run
very long single-request operations and need one, please open an issue.
Getting Help
- Check the API Quick Start Guide
- See examples/api_usage for updated examples
- Join our Discord for migration support
- Report issues on GitHub