Skip to main content

Oxylabs Web API for Hermes Agent

A Hermes Agent plugin that adds the Oxylabs Web API as a provider for Hermes's built-in web_search and web_extract tools.

  • web_search: Google results with titles, URLs and a short outline of each page. Set a country to see results as users in that country do.
  • web_extract: any page as Markdown, including JavaScript-heavy pages (turn on JavaScript rendering) and pages that block plain HTTP clients.

The agent keeps using the tools Hermes already has; you choose Oxylabs as the backend.

Requirements

  • Hermes Agent 0.23.1 or later.
  • An Oxylabs Web API key. Get one in the Oxylabs dashboard.

Set up

  1. Install and enable the plugin:

    hermes plugins install oxylabs/hermes-oxylabs-web-api --enable
    

    Hermes warns that the plugin is not from its reviewed catalog, and asks before installing its one dependency (httpx, which Hermes already uses). In scripts, add --yes-deps.

  2. Add your key. The install asks for it; paste it there, or skip and add it later. To add it later, run hermes tools, open Web Search & Extract, select Oxylabs Web API and paste the key. Or add it to your profile's .env file (~/.hermes/.env for the default profile):

    OXYLABS_WEB_API_KEY=your-web-api-key
    
  3. Select Oxylabs for search, extraction, or both:

    hermes config set web.search_backend oxylabs
    hermes config set web.extract_backend oxylabs
    

Start a new session after these steps.

Settings

Both are optional:

hermes config set plugins.entries.oxylabs-web-api.settings.location US
hermes config set plugins.entries.oxylabs-web-api.settings.render_js true
Setting Default What it does
location none Two-letter country code for searches, such as US or DE.
render_js false Load pages in a browser before extracting them. Slower and uses more credits; turn it on if pages come back nearly empty.

The Hermes desktop app shows the same settings on the plugin's page under Settings → Plugins.

Slow pages are queued on the asynchronous Web API and polled, and each page gets up to 110 seconds, just inside Hermes's 120-second extract timeout.

Your data

  • The plugin sends your search queries and the URLs you ask Hermes to read to https://webapi.oxylabs.io, together with your API key. It contacts no other service. Requests are billed to your Oxylabs account.
  • Oxylabs runs each search and loads each page, so the sites you read receive Oxylabs's request. Before a page is fetched, Hermes checks the address on your machine and blocks private and internal ones.
  • Requests carry an x-oxylabs-sdk: oxylabs-web-api-hermes/<version> header so Oxylabs can count usage per integration. It holds the plugin and Python versions only.
  • The plugin reads the key through Hermes and never includes it in results or error messages. It collects no telemetry, runs no shell commands or background processes, and reads none of your files.

Update or remove

hermes plugins update oxylabs-web-api
hermes plugins remove oxylabs-web-api
hermes config unset web.search_backend
hermes config unset web.extract_backend

Troubleshooting

Problem Fix
OXYLABS_WEB_API_KEY is not set Add the key as in step 2, then start a new session.
rejected the API key (401) The key is wrong or revoked. Check it in the Oxylabs dashboard.
quota is used up (429 QUOTA_EXCEEDED) Top up the plan in the Oxylabs dashboard.
web_search uses another provider Run the hermes config set commands from step 3. Check hermes plugins list shows oxylabs-web-api as enabled.
A page comes back nearly empty Turn on render_js.

Install from PyPI

If you run Hermes from a Python environment you manage yourself, install the package into the interpreter that runs Hermes and enable it:

uv pip install --python /path/to/hermes/python hermes-oxylabs-web-api
hermes plugins enable oxylabs-web-api

hermes plugins update and remove don't manage a PyPI install; upgrade or uninstall it with the same tool.

Development

uv sync --dev
uv run ruff check . && uv run ruff format --check .
uv run pytest                                       # unit tests
OXYLABS_WEB_API_KEY=... uv run pytest -m live       # calls the real API
hermes plugins validate .                           # the checks the Hermes catalog runs

Releases: bump the version in pyproject.toml, both plugin.yaml files and src/hermes_oxylabs_web_api/__init__.py, add a CHANGELOG.md entry, then push a v<version> tag. The Publish workflow publishes to PyPI with trusted publishing.

License

MIT

Metadata

Release files for hermes-oxylabs-web-api 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hermes-oxylabs-web-api 0.1.0
File Size Uploaded Provenance Actions
hermes_oxylabs_web_api-0.1.0.tar.gz 14.5 kB With provenance Details for hermes_oxylabs_web_api-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hermes-oxylabs-web-api 0.1.0
File Interpreter ABI Platform Actions
hermes_oxylabs_web_api-0.1.0-py3-none-any.whl Python 3 none any Details for hermes_oxylabs_web_api-0.1.0-py3-none-any.whl

Total release size: 25.6 kB

Release files / hermes_oxylabs_web_api-0.1.0.tar.gz

Download URL hermes_oxylabs_web_api-0.1.0.tar.gz
Size 14.5 kB
Tags Source
SHA-256 checksum
How to use checksums
6ebf13aaac76f9910de6cb275583cc3f6f43add8e6148094d18f197f6c009b17
BLAKE2b-256 checksum
How to use checksums
c9b18a18ffe21428d459b854f29d4eb85c0abd71f7803cc522f1caf3650e833a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / hermes_oxylabs_web_api-0.1.0-py3-none-any.whl

Download URL hermes_oxylabs_web_api-0.1.0-py3-none-any.whl
Size 11.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
59e41f2737b1c46c17a5138a4bed2047d7b833823b6e1edff5eee9a9ac9087c4
BLAKE2b-256 checksum
How to use checksums
3fd4588ce7f18025f2952d86434a2f2ed62c44df9977b17bc8ef3f2fe2f6c324
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for hermes-oxylabs-web-api 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hermes_oxylabs_web_api-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page