Choose and Configure Hermes Web Search Backends

Hermes exposes two related web tools: web_search returns ranked search results, while web_extract turns one or more URLs into readable text. A backend may support both capabilities or search only. Choose by capability first, then by privacy, cost, deployment effort, and result style.

Hermes currently documents eight backend identifiers: firecrawl, searxng, brave-free, ddgs, tavily, exa, parallel, and xai. You can use one shared backend or configure search and extraction separately.

Match a backend to the workload

Firecrawl is the default full-featured choice. It supports search and extraction and can use the cloud service through FIRECRAWL_API_KEY or a self-hosted endpoint through FIRECRAWL_API_URL.
SearXNG is free, self-hosted, privacy-oriented metasearch. Set SEARXNG_URL. It supports search only, and its JSON response format must be enabled.
Brave Search uses BRAVE_SEARCH_API_KEY and is search only. The backend identifier is brave-free.
DDGS queries DuckDuckGo without an API key and is search only. It needs the ddgs Python package; Hermes may lazy-install it on first use, or an operator can run pip install ddgs.
Tavily uses TAVILY_API_KEY and supports search and extraction.
Exa uses EXA_API_KEY and supports semantic search and extraction.
Parallel uses PARALLEL_API_KEY and supports search and extraction.
xAI uses XAI_API_KEY or hermes auth add xai-oauth and is search only. It calls Grok's server-side web-search tool, so returned titles, descriptions, and URL choices are model-generated rather than verbatim index records.

Firecrawl, Tavily, Exa, and Parallel can serve both tools. SearXNG, Brave, DDGS, and xAI need a separate extract provider whenever the agent must call web_extract.

Paid Nous Portal subscribers can route web search and extraction through the Nous Tool Gateway's managed Firecrawl service without a separate Firecrawl key. New installations can use hermes setup --portal; existing installations can select the web route through hermes tools.

Use the interactive setup for the shortest path

Run the tool picker and choose Web Search & Extract:

hermes tools

The picker asks for the required API key or URL and writes the selection. This is the safest route when configuring a single backend because it avoids spelling a provider identifier incorrectly. Keep secrets in ~/.hermes/.env; non-secret backend selection belongs in config.yaml.

Configure one shared backend

For a deterministic shared choice, set web.backend:

web:
  backend: firecrawl

Any of the eight documented identifiers is valid. Both capabilities fall through to this shared value unless a per-capability override exists. Choosing a search-only provider here means web_extract has no compatible backend unless an extract override or auto-detectable extraction provider is also available.

Split search and extraction

A split is useful when you want free or self-hosted discovery but higher-quality extraction. For example:

web:
  search_backend: searxng
  extract_backend: firecrawl

web.search_backend controls web_search; web.extract_backend controls web_extract. An empty per-capability key falls through to web.backend. If the shared key is also empty, Hermes uses environment-based auto-detection.

The precedence for each capability is therefore explicit per-capability setting, shared web.backend, then auto-detection. Set explicit values in managed or multi-key environments so adding a credential for another feature does not silently change the web provider.

Understand auto-detection

When no backend key is set, Hermes checks available credentials in this documented order:

TAVILY_API_KEY selects Tavily.
EXA_API_KEY selects Exa.
PARALLEL_API_KEY selects Parallel.
FIRECRAWL_API_KEY, FIRECRAWL_API_URL, or a ready Nous Tool Gateway selects Firecrawl.
SEARXNG_URL selects SearXNG.
BRAVE_SEARCH_API_KEY selects Brave.
An importable ddgs package selects DDGS.

xAI is intentionally excluded from auto-detection. Its credentials may also be used for inference, speech, or image features, so Hermes will not redirect web traffic merely because XAI_API_KEY or xAI OAuth exists. Opt in with web.backend: xai.

Account for extraction limits

web_extract applies a deterministic per-page character budget rather than LLM summarization. The default web.extract_char_limit is 15000. Larger pages return a head-and-tail window plus a [TRUNCATED] footer that identifies the saved full text and tells the agent how to read more. The tool's char_limit argument can override the budget for a call.

This behavior is independent of provider selection. A truncated response does not necessarily mean the backend failed or discarded the page. For JavaScript-heavy pages where extracted text is sparse, use browser navigation and snapshots instead of repeatedly changing search providers.

Treat xAI results as model output

Index-backed providers return search records. xAI asks Grok to choose URLs and write the result fields. Validate xAI-selected URLs before fetching them, especially when the query originated in untrusted text. Pair xAI with an extraction provider if you need page contents after discovery.

Pitfalls

Selecting SearXNG, Brave, DDGS, or xAI and assuming web_extract is included.
Leaving several credential variables set and assuming the visually preferred provider will win auto-detection.
Expecting xAI to auto-select from an inference credential.
Forgetting to enable JSON responses on a SearXNG instance, which commonly causes HTTP 403 responses.
Depending on a public SearXNG instance for production uptime or stable rate limits.
Treating a [TRUNCATED] footer as evidence that full text was lost.
Treating xAI-written titles and URLs as verbatim search-index evidence.

Verification checklist

Verify hermes setup reports the intended Web Search & Extract backend.
Verify hermes config get web.backend matches the shared choice when one is configured.
Verify hermes config get web.search_backend and hermes config get web.extract_backend match any split configuration.
Verify web_search returns a small controlled query from the intended provider.
Verify web_extract succeeds on a harmless public page when extraction is required.
Verify every search-only backend has an explicit compatible extract provider or a documented search-only scope.
Verify SearXNG's JSON endpoint responds before blaming Hermes for a 403 or zero-result response.
Verify a fresh session sees tool or backend changes before judging the configuration unsuccessful.