cloudflare-web-search

Cloudflare Web Search backend for Hermes' existing web_search tool, with Ceramic, Exa, or Linkup selected in plugin settings. Search only; keep a separate extract backend. Disclosure — sends queries, result limits, gateway IDs, and optional BYOK aliases to api.cloudflare.com, which forwards searches to the selected provider and records them in AI Gateway logs. Requests can consume gateway credits or provider quota. Reads its own settings and CLOUDFLARE_WEB_SEARCH_API_TOKEN through Hermes' profile-scoped APIs. Registers one web provider, with no new tools, hooks, background processes, file writes, or self-updater. Independent community plugin.

AdolaniumWebv1.0.1Updated 23 days ago

About

hermes-cloudflare-web-search

Cloudflare Web Search provider plugin for Hermes Agent.

Use Ceramic, Exa, or Linkup through Cloudflare Web Search API with Hermes' existing web_search tool.

Quick start

Install the plugin:

hermes plugins install https://github.com/Adolanium/hermes-cloudflare-web-search

Enter a Cloudflare API token when prompted. The token needs Account > Workers AI > Read and Account > AI Gateway > Read permissions. Hermes stores it as CLOUDFLARE_WEB_SEARCH_API_TOKEN in the active profile's secret store. You can also enter it in the Desktop plugin settings or through hermes tools.

Open the plugin's settings under Capabilities > Plugins in Desktop and enter your account ID. Set the gateway ID, provider, and BYOK alias if needed. For CLI setup, merge this into the active profile's config.yaml, preserving other enabled plugins:

plugins:
  enabled:
    - cloudflare-web-search
  entries:
    cloudflare-web-search:
      settings:
        account_id: "YOUR_32_CHARACTER_ACCOUNT_ID"
        gateway_id: default
        provider: ceramic
        byok_alias: ""
web:
  search_backend: cloudflare-web-search
  cache_enabled: false

Set web.cache_enabled: false in the active profile's config.yaml, as shown above. This also applies when you configure the plugin through Desktop. See the search cache limitation.
Run hermes tools and select Cloudflare Web Search under Web Search & Extract, or set web.search_backend as above. Start a new conversation after installation.

The install command works on Windows, macOS, and Linux. The plugin searches only. Keep your existing web.extract_backend for page extraction. Cloudflare requires AI Gateway credits or a provider key stored in AI Gateway. An empty byok_alias lets Cloudflare use its default stored key, then gateway credits. A named alias must already exist.

See Cloudflare's setup guide for account, gateway, and token setup.

Behavior and data handling

Each uncached search sends the query, result limit, selected provider, gateway ID, and optional BYOK alias to api.cloudflare.com. The account ID is in the request path, and the API token is in the Authorization header. Cloudflare forwards the search to the selected provider and records it in AI Gateway logs. Requests may consume gateway credits or provider quota. See Cloudflare's provider documentation for prices and retention policies.

The plugin returns titles, URLs, descriptions, and numbered positions. It accepts queries up to 1,024 characters and requests at most 10 results, matching the beta API's limits. A missing optional description becomes an empty string. HTTP failures and malformed responses return a search error. Requests time out after 30 seconds.

Hermes controls caching and fallback behavior. Its keyless rescue may send a failed search to another service. Set web.keyless_rescue: false if searches must stay on your chosen backend.

Settings and credentials are read for the active profile whenever Hermes calls the provider. A Hermes cache hit skips that call. The plugin does not add model tools, modify Hermes code, start background processes, or update itself. It reads only its own configuration and declared token through Hermes APIs, and writes no files itself.

Search cache limitation

Keep web.cache_enabled: false in every profile using this backend. This is the supported configuration while Hermes' search cache omits the active profile and routing settings from its cache key:

web:
  search_backend: cloudflare-web-search
  cache_enabled: false

With the default cache enabled, repeating a query after changing provider, gateway_id, account_id, or byok_alias can return the previous route's result without calling the new route. The default cache lifetime is 20 minutes. A process serving multiple profiles can also reuse another profile's cached result for the same query and backend.

This limitation is in Hermes' shared search cache. The existing upstream profile-cache PR addresses profile separation, but changes to routing settings within a profile also need an upstream fix. The plugin does not override Hermes' cache or change its registered provider name.

Disabling web.cache_enabled disables both Hermes search and extraction result caches for that profile. Repeated requests can therefore increase network traffic and provider charges.

Verify

After configuring the plugin, ask Hermes to run a search:

hermes chat --toolsets web -q "Use web_search to find the Cloudflare Web Search API documentation."

This sends a live query and may consume Cloudflare credits or provider quota.

Development

From a Hermes source checkout with its test environment prepared, run:

scripts/run_tests.sh /path/to/hermes-cloudflare-web-search/tests/test_provider.py -- -c /path/to/hermes-cloudflare-web-search/pytest.ini
hermes plugins validate /path/to/hermes-cloudflare-web-search --install-deps

The tests install the plugin into temporary profile directories, load it through Hermes discovery, and exercise web_search against a local HTTP server. They require no Cloudflare credentials. Adapter and profile-isolation checks use the documented cache-disabled configuration.

Additional regressions exercise the default cache, the real settings writer, and profile switching. The four routing cases and one profile case are strict expected failures while the upstream cache limitation remains. Their cache-disabled controls must pass. An unexpected pass fails the suite so the limitation and expected-failure markers can be reassessed after an upstream fix.

To reproduce the five upstream failures as ordinary test failures, run:

scripts/run_tests.sh /path/to/hermes-cloudflare-web-search/tests/test_provider.py -- --runxfail -k cache -c /path/to/hermes-cloudflare-web-search/pytest.ini

A live authenticated Cloudflare search remains a separate check. Passing the local suite does not establish live API access or correctness with the default cache enabled.

License

MIT. Cloudflare, Ceramic, Exa, and Linkup are trademarks of their respective owners. This is an independent community plugin, unaffiliated with Cloudflare or Nous Research.

README from the reviewed commit 259783b; it updates when the author re-pins.

More by Adolanium

25 plugins by Adolanium in the catalog.

AdolaniumgadgetTalk to your Hermes from small ESP32 devices with a screen, microphone and speaker: hold a button, ask, and hear the answer. Adds a gateway platform where each device is a chat, plus tools to list devices, show a card on a screen and run device actions (LEDs, relays). Disclosure — the gateway listens for devices on a WebSocket port (8765, all interfaces by default; plain ws:// unless tls_cert/tls_key are set). New devices need a Hermes pairing code unless listed in GADGET_ALLOWED_USERS; GADGET_ALLOW_ALL_USERS skips pairing (development only). A paired device answers the agent's command approvals for its own chat (allow once or deny), within Hermes's approval timeout. The first approved device becomes the platform's home channel by default. Session hooks feed a dashboard on paired devices with each agent session's platform, a short id and its state (idle, busy, waiting for approval); a device that can switch profiles also sees the offered profiles' sessions. Optional profile switching (off unless `profiles` is set in the default profile's gadget config) lets a device paired on the default profile talk to the listed profiles; each profile approves the device through its own pairing flow (the device shows the `hermes -p <profile> pairing approve` command), the plugin writes nothing into other profiles, and revoking the device in the default profile sends it back there. A paired gadget that draws faces gets the answering profile's face: its `gadget-face.bin`, or its Hermes avatar (`assets/avatar.*`) converted with Pillow when installed; the plugin only reads these files, and `profile_faces: false` turns this off. `platforms.gadget.extra.stt_language` sets the transcription language of gadget recordings through the `pre_transcription` hook; other platforms' audio is untouched. Spoken replies that are not WAV are converted with the local ffmpeg; Opus reply audio uses the host's libopus when installed (loaded with ctypes, not bundled). `hermes gadget update --latest` downloads firmware from this repository's GitHub releases, checks size and SHA-256 against the release manifest (files carry build provenance attestations) and sends it to the device. A device that advertises `camera.capture` returns stills that are saved as PNGs under `~/.hermes/gadgetpix/` and kept until removed by hand. A Hermes Desktop page (`desktop/plugin.js`, plugin SDK only) runs a gadget in the window that connects to the local gateway as a device of its own: its device key, and the gateway access token when one is required, are kept in the page's plugin storage, it pairs like any device, and it uses the microphone only while its talk button or Space is held. The plugin's dashboard routes, behind the dashboard's login, can approve the pairing code a device is showing and send a card or run an advertised action on a connected, paired device; the requests pass through files under plugin-data/gadget/desk/. Otherwise writes only under plugin-data/gadget/. Uses Hermes's own STT, TTS and image cache; no telemetry. Independent community project, not affiliated with Nous Research.Communityplatform518 Adolaniumhermes-resetwatchTrack subscription quotas and reset times in Hermes Desktop. Disclosure — probe.py re-executes itself under the Hermes Python interpreter located via HERMES_PYTHON / VIRTUAL_ENV / the parent process or the Hermes installer's managed venv (HERMES_HOME/installs). Every credential read is read-only and nothing is refreshed or stored: it reads provider API keys from the process environment, the Hermes .env (through Hermes's get_secret helper, else read directly), the Vaultwarden plugin's local secret cache (cache/vaultwarden_cache.json, only when Vaultwarden is the sole enabled secret source, keyed by a hash of BW_SESSION, which is never sent) and Docker s6 container env files; Hermes's saved OAuth logins (the credential pool through Hermes's read_credential_pool helper, else auth.json directly, and HERMES_HOME/.anthropic_oauth.json); and other coding-assistant CLIs' local logins: Claude Code (credentials file, macOS keychain or Windows Credential Manager), Codex, Cursor (macOS keychain and the IDE's state.vscdb, opened read-only), Kimi, Grok, ZCode and Command Code. For GitHub Copilot (on by default) it tries COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN (through Hermes get_secret, else the process environment), then the Copilot editor's apps.json / hosts.json, then runs gh auth token (prompts disabled, 3-second limit), trying each token in turn until GitHub accepts one. For Codex, a 401 or 403 is retried once with another saved login for the same account. It sends each key only to its own vendor's usage endpoint, presenting the vendor client's identity headers where a private endpoint expects them (Claude Code and Codex CLI user agents, the Grok CLI client headers, and for Copilot the VS Code / Copilot Chat editor headers on api.github.com/copilot_internal/user, which GitHub does not document); environment variables such as GROK_CLI_CHAT_PROXY_BASE_URL (honored only for https grok.com / x.ai hosts), CLAUDE_CONFIG_DIR, CODEX_HOME and GROK_HOME change which host or file it uses. Usage results are cached under HERMES_HOME/cache/resetwatch, never tokens. It exposes nothing to the model: it is a Desktop page only.CommunityDesktop app83 Adolaniumhermes-rssRead RSS and Atom feeds and discuss articles in Hermes Desktop. Disclosure — feeds and full articles are fetched with curl through the gateway's shell.exec on the connected Hermes host (public-IPv4 SSRF guard); opt-in AI grading sends article excerpts to your configured model and creates HERMES_HOME/skills/rss-importance-grading/SKILL.md if missing; opt-in image loading fetches publisher images directly from Desktop.CommunityDesktop app65 Adolaniumhermes-tailscaleBrowse Tailscale devices and connect to remote Hermes instances in Hermes Desktop.CommunityDesktop app60

All 25 by Adolanium

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section