Hermes Agent
Hermes Agent web search: backends, setup and fixes
Updated 19 November 2026
Hermes Agent gives the model two web tools, one for searching and one for reading pages. Several providers can sit behind them, some of them free, and you can use one provider for each tool. This page lists the backends, shows how to choose and configure one, and covers the errors listed in the documentation’s troubleshooting section.
Facts come from the Web Search & Extract page and the Tool Gateway page of the Hermes Agent 0.23.2 documentation, read on 19 November 2026. Free tiers and prices are the vendors’ to change, so check the vendor before you rely on a number.
The two web tools
The documentation describes two model-callable tools:
web_search. Searches the web and returns ranked results.web_extract. Fetches and extracts readable content from one or more URLs.
Both are set up through one backend choice, made in hermes tools or directly in config.yaml. Not every backend can do both, which is the main thing to understand before you pick one.
This is a different job from the browser tool. Web search returns results and page text from a provider. The browser tool, covered on our browser page, drives a real page. The docs point to the browser route when a JavaScript-heavy page gives back little content through extraction. For that side, including cloud browsers, see Hermes Agent browser.
Which backends search and which extract
This is the table from the documentation, trimmed to what you need to choose:
| Backend | Credential | Search | Extract |
|---|---|---|---|
| Firecrawl (default) | FIRECRAWL_API_KEY, optional | Yes | Yes |
| SearXNG | SEARXNG_URL | Yes | No |
| Brave Search (free tier) | BRAVE_SEARCH_API_KEY | Yes | No |
| DDGS (DuckDuckGo) | None | Yes | No |
| Exa | EXA_API_KEY, optional | Yes | Yes |
| Parallel | PARALLEL_API_KEY, optional | Yes | Yes |
| Tavily | TAVILY_API_KEY, optional | Yes | Yes |
| Perplexity | PERPLEXITY_API_KEY | Yes | Yes, as query-relevant snippets |
| Keenable | KEENABLE_API_KEY, optional | Yes | Yes |
| xAI (Grok) | XAI_API_KEY or hermes auth add xai-oauth | Yes | No |
| OpenAI Native (Codex) | hermes auth add openai-codex | Yes | No |
The docs call Brave Search, DDGS, xAI and OpenAI Native search-only, and say to pair any of them with an extract-capable provider when you also need web_extract. The same goes for SearXNG.
Two of the search-only options work differently from a normal search index. The docs say xAI runs Grok’s server-side search and that the results are model output, so a crafted query could in principle steer it towards attacker-chosen URLs. Treat those URLs like any model-generated link and validate them before fetching. OpenAI Native needs a ChatGPT or Codex subscription login and works only on the Codex Responses endpoint; on a custom OpenAI-compatible base_url or a non-OpenAI model the normal web_search function is left as it is.
Perplexity’s extract returns the passages that matter, not the whole page. The docs suggest Firecrawl, Exa or Parallel as the extract backend when you need the full text.
Free options
A fresh install with no web credentials at all gets working search and extract. The docs describe a keyless free-tier rotation: requests rotate round-robin across the public free tiers of Exa, Parallel, Firecrawl and Keenable, and rate-limited requests retry on the next vendor. Searches also retry on the next vendor when a vendor refuses them. It is described as a last resort, and any configured backend or key takes priority over it. For steady, unthrottled service the docs recommend a keyed provider. Turn the rotation off with:
web.keyless_fallback: falseThe other free routes the documentation names, with its figures:
- SearXNG. Free and self-hosted. The docs describe it as an open-source metasearch engine that aggregates results from 70+ search engines.
- DDGS. Free, with no key. It uses the
ddgsPython package, which Hermes can install on first use. - Firecrawl. The docs list 500 credits a month on the free tier. They also describe a keyless cloud route when it is selected.
- Brave Search. The docs list 2,000 queries a month on the free tier.
- Exa. The docs list 1,000 searches a month with a key, and a keyless route.
- Tavily. Select it in
hermes toolsor setweb.backend: tavilyto use it without an account; the docs say it is rate-limited. Set a key for higher limits.
For Exa, Parallel and Keenable, hermes tools shows two rows each, Free (keyless) and Paid (API key). Choosing Free pins the anonymous endpoint even if you add a key later. Choosing Paid pins the keyed path, so a missing key becomes an error instead of a quiet downgrade. The choice is stored as web.provider_tier.<name>, set to free or paid. For wider cost questions, see is Hermes Agent free.
Choose and configure a backend
You can choose a provider through the menu. Run this, open Web Search & Extract and pick a provider:
hermes toolsThe wizard asks for the URL or key the provider needs and writes it to your config. To do it by hand, keys go in ~/.hermes/.env:
# ~/.hermes/.env
FIRECRAWL_API_KEY=fc-your-key-hereTo run your own Firecrawl instead of the cloud API, the docs use FIRECRAWL_API_URL, for example http://localhost:3002. For this keyless self-hosted setup, the docs also specify disabling authentication on your Firecrawl server with USE_DB_AUTHENTICATION=false.
One backend for everything is a single key in ~/.hermes/config.yaml:
web:
backend: "searxng"The docs list these values for web.backend: firecrawl, searxng, brave-free, ddgs, tavily, perplexity, keenable, exa, parallel and xai. OpenAI Native is selected through web.search_backend with the value openai-native.
How Hermes picks when you have not chosen: when no per-capability override applies and no shared backend has ever been selected, it checks these in order: Tavily, Perplexity, Exa and Parallel keys; a Firecrawl key or FIRECRAWL_API_URL; a ready Nous Tool Gateway; SEARXNG_URL; BRAVE_SEARCH_API_KEY; and the ddgs package. Next, any Nous identity, including an anonymous guest, provides managed web_search only. With none of these present, Hermes uses the keyless ring. Once a shared selection exists, the docs say the runtime always uses it, and adding a key to .env does not reroute web traffic. xAI is never auto-detected, because those credentials are also used for other things; you opt in with web.backend: "xai".
To confirm what Hermes sees, the docs say hermes setup shows the detected web backend.
SearXNG, the free self-hosted route
SearXNG takes a URL instead of a key: you only need a running instance. Its JSON output is off by default, so enabling it is the step that matters. The docs recommend self-hosting with Docker for a private instance without rate limits. If Docker is new to you, Hermes Agent in Docker covers the basics of that side. The documented outline:
- Run the
searxng/searxng:latestimage, publishing container port 8080 on host port 8888 and mounting a config folder at/etc/searxng. - Copy the generated
settings.ymlout of the container and add the JSON format:
search:
formats:
- html
- json- Copy the file back into the container and restart it.
- Test it. The docs use a request to
http://localhost:8888/search?q=test&format=json, and a403 Forbiddenmeans JSON is still disabled. - Point Hermes at it, in
~/.hermes/.env:
SEARXNG_URL=http://localhost:8888Then select it as the search backend in ~/.hermes/config.yaml:
web:
search_backend: "searxng"A public instance from searx.space is the alternative: filter for instances with JSON format enabled and set SEARXNG_URL to its address. The docs caution that public instances have rate limits, variable uptime and may turn JSON off at any time, and they strongly recommend self-hosting for production use.
Mixing a search backend with a different extract backend
Search and extract can use different providers. Pair a search-only backend with an extract-capable provider, for example:
# ~/.hermes/config.yaml
web:
search_backend: "searxng"
extract_backend: "firecrawl"The comment in the docs offers tavily, perplexity, keenable, exa and parallel as other extract choices. The order of precedence, per capability, is the explicit web.search_backend or web.extract_backend first, then web.backend, then auto-detection. A per-capability key only affects its own capability, so setting web.extract_backend alone leaves search on whatever it would otherwise use.
Two more settings help with long pages. web.extract_char_limit sets how much of a page reaches the agent, with a default of 15000 characters, clamped between 2000 and 500000. Longer pages are cut to a head and tail window with a [TRUNCATED] footer, and the extracted text is saved to disk. For pages over 2,000,000 characters, stored text is capped at 2 MB. The footer provides the file path and the exact read_file call for reading omitted content from the saved file. web.extract_timeout bounds each provider call, default 120 seconds. The docs also describe caching of repeated searches and extracts, controlled by web.cache_enabled and web.cache_ttl_minutes; if you need every call fresh, lower the TTL or turn the cache off.
When keyless fallback and rescue are enabled, a failed call to your chosen backend retries on the keyless ring. The result notes which vendor served it, and the next call tries your chosen backend again. Disable that with web.keyless_rescue: false.
The Nous Tool Gateway route
With a paid Nous Portal subscription, web search and extract are available through the Tool Gateway as managed web search. The docs say this needs no separate web vendor account, and that gateway tools are billed against your Nous subscription as you use them. A new install can run:
hermes setup --portalAn existing install can switch only the web tool in hermes tools. In config.yaml the value is nous, and it can be set for each capability, so you can keep your own key for one and use the gateway for the other:
web:
search_backend: firecrawl
extract_backend: nousThe Tool Gateway page also notes that a model picker will not offer the gateway for a tool you have explicitly pointed at another backend, so your own choice is not overwritten. For plans and keys, see Hermes Agent with Nous Portal.
Common errors
web_searchreturns{"success": false}. With SearXNG, check thatSEARXNG_URLanswers. A 403 means JSON is disabled, so addjsontoformatsinsettings.ymland restart. A connection error can mean the container is not running.web_extractsays “search-only backend”. SearXNG cannot extract. Setweb.extract_backendto a provider that can.- SearXNG returns 0 results. Some public instances disable certain engines or categories. Try another query, another instance, or your own.
- Rate limited on a public instance. Switch to a self-hosted one.
- Truncated content with a footer. That is expected for pages over the character budget. Raise
web.extract_char_limitor pass a largerchar_limiton the call. - Added a key to the .env file and nothing changed. If a shared backend was already selected, the runtime keeps using it. Select the provider in
hermes toolsor editweb.backend. - No web tools at all. With
web.keyless_fallback: false, no credentials and no Nous identity, web tools are unavailable until a provider is configured. A Nous identity, including an anonymous guest, still provides managedweb_search;web_extractneeds a configured provider.
If you want to search X posts specifically, the docs describe a separate x_search tool, and say to keep using web_search and web_extract for general web pages.
Web search on ReadyHermes
Every ReadyHermes assistant comes with web search, a real web browser and its own Linux computer. You ask in chat and it searches; there is nothing to set up, and you do not need to buy a search provider key. We do not state which search backend sits behind it or how many searches you get.
The workspace has no screen for choosing a backend or pasting a Firecrawl, Tavily, Brave or Exa key. Using your own search provider key on a ReadyHermes assistant is not tested and not supported today, so the setup in this guide is for Hermes you run yourself. Plans start at US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month and a 1-hour free trial. See managed Hermes Agent hosting.
Questions
Which Hermes Agent web search backends can also extract pages?
According to the Hermes docs, Firecrawl, Exa, Parallel, Tavily, Perplexity and Keenable can search and extract. SearXNG, Brave Search, DDGS, xAI and OpenAI Native are search-only. Perplexity extracts query-relevant snippets rather than whole pages.
Is there a free way to run web search in Hermes Agent?
Yes. A fresh install with no web credentials rotates across the free tiers of Exa, Parallel, Firecrawl and Keenable. SearXNG (self-hosted) and DDGS are free too, and the docs list free tiers for Firecrawl (500 credits a month), Brave (2,000 queries a month) and Exa (1,000 searches a month with a key). Check the vendors for current limits.
How do I set SearXNG as the search backend?
Run an instance with JSON format enabled, set SEARXNG_URL in ~/.hermes/.env, and set web.search_backend to searxng in ~/.hermes/config.yaml. You can also pick it in hermes tools. SearXNG cannot extract, so add an extract backend as well.
Can I use one provider for search and another for extract?
Yes. Set web.search_backend and web.extract_backend separately in config.yaml, for example searxng for search and firecrawl for extract. Each key affects only its own capability, and an empty one falls back to web.backend.
Can I choose a web search backend on ReadyHermes?
No. ReadyHermes assistants come with web search built in and the workspace has no screen for choosing a backend or pasting a search provider key. Using your own search key there is not tested and not supported today.