Odysseus AI SearXNG Setup: Connect, Test, and Fix Web Search

How the Odysseus AI SearXNG setup works

SearXNG is the default self-hosted search provider in the current Odysseus interface. Web Search and Deep Research send requests to the configured provider, while the model receives the returned sources and extracted text. The model itself does not replace the search service.

The key networking rule is context. On the host, localhost:8080 points to the published SearXNG port. Inside the Odysseus Docker container, localhost points back to the Odysseus container, so the correct Compose service address is http://searxng:8080.

Use the bundled Docker SearXNG service

The official Compose file starts Odysseus, SearXNG, ChromaDB, and ntfy together. It binds SearXNG to 127.0.0.1:8080 on the host and injects the internal service URL into Odysseus. Start the whole stack from the repository root instead of launching only the application container.

The official file deliberately pins SearXNG to 2026.5.31-7159b8aed as of this page's review date. Do not replace it with :latest merely to chase freshness; the project comments explain that a newer upstream image previously failed its health check.

1. Create the environment file

   Copy .env.example to .env and keep SEARXNG_SECRET blank unless you need a fixed secret. Docker generates and stores a secret on first boot.

2. Start the complete stack

   Run docker compose up -d --build from the cloned Odysseus directory.

3. Wait for health checks

   Run docker compose ps and confirm both odysseus and searxng are running; Odysseus waits for the search container to become healthy.

4. Inspect failures before rebuilding

   Use docker compose logs searxng --tail=100. Permission, settings-volume, image-pull, or port-conflict messages usually identify the root cause.

docker compose up -d --build

docker compose ps

docker compose logs searxng --tail=100

Connect Odysseus AI to an external SearXNG instance

Use an external instance when SearXNG runs outside the official Compose network. Set SEARXNG_INSTANCE in .env to the final base URL reachable from the Odysseus process, then restart Odysseus so it reloads the environment.

Test from the same network context as Odysseus. A URL that opens in your desktop browser can still fail inside Docker because of DNS, TLS trust, firewall rules, proxy authentication, or a private hostname that the container cannot resolve. Public shared SearXNG instances may rate-limit, block JSON responses, or change without notice, so a controlled self-hosted instance is more predictable.

SEARXNG_INSTANCE=http://localhost:8080

SEARXNG_INSTANCE=https://search.example.com

docker compose up -d --force-recreate odysseus

Select SearXNG and verify search in Odysseus

Open Settings, choose the Search panel, set Provider to SearXNG, and use the Test button. The current interface also lets Deep Research use the same web-search provider or select SearXNG explicitly. A successful provider test is more useful than checking only whether port 8080 opens, because it exercises the configuration Odysseus will actually use.

After the provider test passes, run one narrow query in chat with web search enabled. Confirm that the answer includes current sources. For Deep Research, start with a small topic before raising token limits or extraction concurrency.

• Provider Test succeeds in Settings → Search.
• A chat search returns source links rather than only model memory.
• Deep Research can fetch and extract at least one reachable page.
• SearXNG remains bound to a private interface unless you intentionally protect and expose it.

Troubleshoot Odysseus AI SearXNG errors

Diagnose the first failing layer instead of changing several settings at once. Start with container health, then network reachability, then the provider test, and only then the quality of returned results.

Version freshness and security notes

This site checked the canonical odysseus-dev/odysseus repository on July 22, 2026. The repository had no GitHub Releases or tags, so this guide does not label a build as the latest stable version. It follows the official dev-branch Compose and setup files and records the SearXNG image pinned by that source.

Keep SearXNG, model servers, ChromaDB, and other raw service ports private. The official Compose defaults bind SearXNG to 127.0.0.1. If you move it to another host, use authentication or a trusted private network, valid TLS, and explicit firewall rules. Expose the authenticated Odysseus entry point rather than the raw search backend.