Skip to the page
Get started free

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

What you need

  • Hermes Agent, with its bundled SearXNG web backend.
  • A SpecStream key. Get your key on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card.

  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
    SEARXNG_URL=https://api.specstream.ai/searxng/YOUR_SPECSTREAM_KEY

  2. 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
    web:
      search_backend: "searxng"

  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
    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. 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.

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.

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. 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 [email protected].

More

SpecStream for Hermes Agent web search covers what it does in Hermes Agent web search on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and the matches are paid from your balance. Billing has the details. For help, email [email protected].