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.

docs(websocket): document auth requirement for WS handshake (#3658)

LearningCircuitac23d3f847b0
diff --git a/docs/env_configuration.md b/docs/env_configuration.md
index d491959a22..d9c4618c95 100644
--- a/docs/env_configuration.md
+++ b/docs/env_configuration.md
@@ -191,6 +191,8 @@ For the full list of database configuration variables, defaults, constraints, an
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](CONFIGURATION.md#pre-database-env-only-settings).
+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)
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 904cae373f..914a735a49 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -305,12 +305,17 @@ python -m local_deep_research.web_search_engines.rate_limiting export --format c
- Open browser DevTools > Network > WS
- Look for `/socket.io` connections
-3. **Firewall/proxy issues:**
+3. **Authentication / expired session:**
+ - WebSocket connections require an authenticated session.
+ - If your session has expired, or the server was restarted while your tab was open, the handshake is rejected and the UI may silently fall back to HTTP polling with no progress shown.
+ - Log out and back in to restore the connection.
+
+4. **Firewall/proxy issues:**
- WebSocket needs persistent connections
- Some proxies don't support WebSocket
- Try direct connection (no proxy)
-4. **Fallback to polling:**
+5. **Fallback to polling:**
- The client automatically falls back to HTTP polling
- Check if polling requests are working