> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/hermes-web-search. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt # Hermes Agent web search Set `SEARXNG_URL` to SpecStream's address and select `searxng` for search, and Hermes Agent's `web_search` tool runs on the SpecStream Search API. Hermes's own SearXNG backend stays as it is. There is no SearXNG server to host and no JSON setting to turn on. [SpecStream for Hermes Agent web searchAI assistants](https://specstream.ai/integrations/hermes-web-search.md) ## What you need - Hermes Agent, with its bundled SearXNG web backend. - A SpecStream key. [Get your key](https://specstream.ai/workspace/search?route=searxng&utm_source=hermes&utm_medium=howto) on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card. 1. 1 ## 1. Put the address in ~/.hermes/.env Hermes's SearXNG backend sends no key of its own, so the key goes in the address. Add this line to `~/.hermes/.env`, with your key in place of `YOUR_SPECSTREAM_KEY`. Give the address without `/search`: Hermes adds `/search` itself. The address holds your key. Keep `~/.hermes/.env` out of git and out of anything you share. ~/.hermes/.env ```bash SEARXNG_URL=https://api.specstream.ai/searxng/YOUR_SPECSTREAM_KEY ``` 2. 2 ## 2. Select SearXNG for search In `~/.hermes/config.yaml`, set `search_backend` under `web`. The search setting wins over `web.backend`, so search moves to SpecStream and `web_extract` stays on the provider you use today. Leave `extract_backend` as it is: this address answers searches only. Or run `hermes tools`, open **Web Search & Extract** and pick SearXNG. Hermes asks for the URL and writes it for you. Start a new Hermes session so it reads both files. If you use the messaging gateway, run `hermes gateway restart`. ~/.hermes/config.yaml ```yaml web: search_backend: "searxng" ``` 3. 3 ## 3. Check the address Send the same request Hermes sends, from a terminal. It prints the number of results, or SpecStream's message when the key is wrong. This check is one search. Terminal ```bash curl -s "https://api.specstream.ai/searxng/YOUR_SPECSTREAM_KEY/search?q=test&format=json&pageno=1" | python3 -c "import sys, json; d = json.load(sys.stdin); print(len(d.get('results', [])), 'results', d.get('error', ''))" ``` 4. 4 ## 4. Ask Hermes Ask something recent, so Hermes calls `web_search`: `Search the web: what changed in the latest Python release?` ## What Hermes sends Each `web_search` call is `GET` on `SEARXNG_URL` plus `/search`, with `q`, `format=json` and `pageno=1`. SpecStream answers in SearXNG's JSON shape: `results[]` with `title`, `url`, `content` and `score`, up to 10 results a call. Hermes sorts the results by `score`, keeps as many as the tool call asked for (5 when it names none) and gives `content` to the model as each result's description. Hermes keeps a repeated search in memory for 20 minutes by default (`web.cache_ttl_minutes`). A repeat inside that window sends nothing to SpecStream and costs nothing. ## Why not run SearXNG yourself Hermes's own SearXNG setup is seven steps: a Docker Compose file, copying `settings.yml` out of the container, adding `json` to `search.formats`, and a restart. SearXNG ships with JSON output off and answers `403 Forbidden` until you turn it on. Hermes's docs add that public instances have rate limits, variable uptime, and may turn JSON off at any time. With the SpecStream address there is no container and no settings file, and the searches run from SpecStream's servers, not from your machine's address. The Search API is the most accurate web search API on SimpleQA Verified and WideSearch. Scores and method are on [the benchmarks page](https://specstream.ai/benchmarks.md). ## When a search fails - A wrong key gets `401`, and Hermes reports `SearXNG returned HTTP 401`. With `web.keyless_rescue` on, which is the default, Hermes then answers that one call from its keyless free tier and adds `backend_error` to the result. A bad key can look like working search, so set `keyless_rescue: false` under `web` while you check the setup, or run the check in step 3. - When the account has used its calls for the minute, SpecStream answers `429`. Hermes reports it as an HTTP error, and the rescue above applies the same way. - A message that starts with `Could not reach SearXNG at` prints the whole address, key included. Check that `SEARXNG_URL` starts with `https://api.specstream.ai/searxng/`, and keep that log private. ## Cost Each `web_search` call is one Search API call on the fast tier: $1 per 1,000 searches of up to 10 results. It comes out of your balance, with no quote and no approval. A search that returns no results costs nothing, and every call is in your account's request log. New accounts start with $10 of credit, no card. See [pricing](https://specstream.ai/pricing.md). ## Lists of records as well The SearXNG address gives Hermes search results. For Deep Search, which returns every match as structured rows, add SpecStream to Hermes as an MCP server with the [Hermes Agent MCP guide](https://specstream.ai/docs/integrations/hermes.md). Both use the same account. ## Turn it off Remove `search_backend` from `web` in `config.yaml`, or pick another provider in `hermes tools`, and delete the `SEARXNG_URL` line. To end the key's access, revoke it under **Agents & API** in your SpecStream workspace. Questions go to [support@specstream.ai](mailto:support@specstream.ai). ## More [SpecStream for Hermes Agent web search](https://specstream.ai/integrations/hermes-web-search.md) covers what it does in Hermes Agent web search on one page. Every other tool has its guide in [Connect your tools](https://specstream.ai/docs/integrations.md). You see the most a request can cost before it starts, and the matches are paid from your balance. [Billing](https://specstream.ai/docs/billing.md) has the details. For help, email [support@specstream.ai](mailto:support@specstream.ai).