Odysseus uses SearXNG as its privacy-respecting web search backend. The Agent’s web tool, Deep Research’s multi-step source gathering, and the direct search panel in the UI all route queries through SearXNG. If you are running Docker Compose, SearXNG is already bundled and configured — you do not need to do anything for it to work. For native installs you need to run SearXNG separately and point Odysseus at it.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/pewdiepie-archdaemon/odysseus/llms.txt
Use this file to discover all available pages before exploring further.
Docker Compose (default)
Docker Compose starts a SearXNG container alongside Odysseus automatically. Inside the Compose network, Odysseus reaches SearXNG athttp://searxng:8080. On the host machine, SearXNG is exposed on port 8080 bound to 127.0.0.1 by default, so it is reachable from the host at http://localhost:8080 but not from your LAN or the internet.
The SEARXNG_INSTANCE environment variable is automatically overridden to http://searxng:8080 inside the Compose network — you do not need to set it manually.
SearXNG binds to
127.0.0.1 by default in the Docker Compose setup. Do not expose it publicly. SearXNG has no authentication — anyone who can reach it can use it as an open proxy.Native install
For a native Linux or macOS install, you need to run SearXNG yourself and tell Odysseus where to find it:Install SearXNG
Follow the official SearXNG installation guide. A quick Docker one-liner also works:
Using an external SearXNG instance
You can point Odysseus at any reachable SearXNG instance — a self-hosted instance on another machine, a Tailscale peer, or a shared team instance:SEARXNG_INSTANCE to the full base URL of the instance. Odysseus will append /search and query parameters as needed.
SEARXNG_SECRET
SEARXNG_SECRET is SearXNG’s internal cookie and CSRF protection secret. When running in Docker, a random secret is generated on first boot and stored in the searxng-data volume — no action required. For native installs you can leave it unset (SearXNG will generate its own), or pin it explicitly if you want reproducible behavior across restarts:
DuckDuckGo as an alternative
If you prefer DuckDuckGo over SearXNG — for example, in a native install where you don’t want to run SearXNG at all — install the optional dependency:requirements-optional.txt. After installing it, select DuckDuckGo in Settings → Search and restart Odysseus.
duckduckgo-search is an unofficial library and depends on DuckDuckGo’s HTML scraping interface, which can break when DuckDuckGo changes its site layout. SearXNG is more reliable for production use.How search is used
| Feature | How it uses search |
|---|---|
| Agent web tool | The agent calls web_search with a query and gets back a context string plus source links, which it can then cite or follow up on. |
| Deep Research | Multi-step research runs use SearXNG to find and rank sources, then fetch and synthesize the content of top results. |
| Direct search (UI) | The search panel in the Odysseus UI queries SearXNG directly and returns results inline. |
Troubleshooting
Agent says web search is unavailable
Agent says web search is unavailable
SearXNG returns no results
SearXNG returns no results
SearXNG aggregates external search engines. If all of its configured engines are rate-limiting it, results may be empty. Check the SearXNG admin panel (usually at
http://localhost:8080/admin) for engine health. The default Docker config has a working set of engines; you may need to adjust them for your region or network.Docker: SearXNG not reachable from host
Docker: SearXNG not reachable from host
By default
SEARXNG_BIND=127.0.0.1 — the port is only accessible on the host machine, not your LAN. This is intentional. If you need LAN access (e.g. to inspect it from another device), set SEARXNG_BIND=0.0.0.0 in .env, but be aware there is no authentication.