Skip to content

Use local SearXNG for agent web search

Keryx can use a SearXNG instance that you operate yourself. It is an explicit search-provider option, not a general permission for the agent to access your local network. The default web_search engine is DuckDuckGo and needs no instance; see Agent web search.

Start SearXNG

For a quick local instance, follow the official SearXNG installation guide. A typical Docker command is:

docker run --rm -p 8080:8080 searxng/searxng

Keryx does not run Docker or alter your SearXNG configuration.

Connect it in Keryx

In agent mode:

  1. Run /search-provider and choose SearXNG.
  2. Confirm or edit the default URL http://localhost and port 8080.
  3. Run the connection test. A provider is not considered connected until this request returns the expected SearXNG JSON result shape.
  4. Run /search-connect and select SearXNG. That list intentionally includes only providers with a successful connection test.

Then the agent uses SearXNG for web_search instead of DuckDuckGo. If SearXNG later fails its connection test, keryx does not silently switch back to DuckDuckGo — reconnect or /search-connect duckduckgo explicitly.

Troubleshooting

  • Connection refused: make sure SearXNG is running and its published port matches the configured port.
  • Incompatible response: the configured endpoint must expose SearXNG's /search?...&format=json API, not an HTML error page or a reverse-proxy login page.
  • Provider disappears from /search-connect: edit/test it again. Changing configuration invalidates its connected state until a new test succeeds.

The SearXNG exception is limited to its configured loopback endpoint. It does not make web_fetch or cloud search providers able to access private addresses.