For AI agents: a documentation index is available at /llms.txt
Skip to main content

Hermes Agent

Hermes Agent is NousResearch's open-source AI agent. This guide configures Browserless as its browser: managed cloud sessions with stealth, automatic CAPTCHA solving, residential proxies, and cascading scrape strategies, through one MCP server and one API token.

Prerequisites

Why Browserless as Hermes's browser​

Most automation targets use bot detection, login walls, or CAPTCHAs. Browserless handles these by default, so one configuration works on protected sites and permissive ones alike:

  • browserless_smartscraper runs cascading strategies on every request: direct fetch, then proxy, then headless browser, then CAPTCHA solving, until the content returns.
  • browserless_agent can preserve cookies and page state through logins, multi-step forms, and pagination. In v1.33.0+, multi-call sessions require first-call opt-in: set keepSessionAlive: true, then echo the returned sessionId on later calls.
  • The browsers run on Browserless's cloud rather than the machine running Hermes. A single API token covers stealth, residential proxies, and CAPTCHA solving; there are no separate provider accounts to set up.
  • The same server exposes nine tools covering scraping, search, crawling, exports, Lighthouse audits, and file downloads.

Hermes's built-in browser tools work for public, permissive pages. We recommend Browserless for automation workloads because the unblocking, proxying, and solving are built into every request instead of configured per site.

Step 1: Add the server to your config​

Hermes configures MCP servers in ~/.hermes/config.yaml. The Browserless server is remote, so it needs only a URL and your token. Put the token in ~/.hermes/.env so it stays out of the config file:

# Add to ~/.hermes/.env
BROWSERLESS_API_TOKEN=YOUR_API_TOKEN_HERE

Then reference it from the config. Hermes expands ${VAR} in server entries from .env or the process environment:

mcp_servers:
  browserless:
    url: "https://mcp.browserless.io/mcp"
    headers:
      Authorization: "Bearer ${BROWSERLESS_API_TOKEN}"

The hosted server speaks the Streamable HTTP transport, which is what Hermes uses for URL-based servers. No local process, Node, or Docker is required.

Step 2: Verify the tools loaded​

Start Hermes from the terminal and ask it what it can do:

hermes chat
Tell me which MCP-backed tools are available right now.

The reply should list the Browserless tools. Hermes prefixes MCP tools with the server name, so they appear as mcp__browserless__browserless_agent, mcp__browserless__browserless_smartscraper, and so on. If you edited the config while Hermes was running, reload it with /reload-mcp. See the full tool list in the MCP server reference.

Step 3: Try it on a real task​

Give Hermes a task its built-in browser tends to get blocked on:

Use the Browserless tools to scrape https://www.browserless.io/pricing
and list each plan with its unit allowance, then tell me which strategy
the scraper used.
Use the Browserless agent to open https://docs.browserless.io, navigate
to the BaaS quickstart, and summarize the setup steps.

Optional: Limit which tools load​

The server exposes nine tools. If you want a smaller surface, use Hermes's tool filtering to whitelist just the ones you need:

mcp_servers:
  browserless:
    url: "https://mcp.browserless.io/mcp"
    headers:
      Authorization: "Bearer ${BROWSERLESS_API_TOKEN}"
    tools:
      include: [browserless_agent, browserless_smartscraper]

browserless_agent plus browserless_smartscraper covers most workflows: one stateful browser for interaction, one stateless scraper for content.

FAQ & Troubleshooting​

Can I point Hermes's /browser connect at a Browserless CDP endpoint instead?

No. /browser connect is built for local Chromium-family browsers: its readiness probe requests /json/version without preserving the URL's query string, so an authenticated endpoint like wss://production-sfo.browserless.io?token=... fails the check. Use the MCP route on this page, which authenticates properly and exposes richer tools than raw CDP.

Hermes doesn't list any Browserless tools

Run /reload-mcp if you changed config.yaml during a session, and check the Hermes logs for a connection error. The usual causes are a URL typo (the endpoint must be exactly https://mcp.browserless.io/mcp), an expired token, or BROWSERLESS_API_TOKEN not being set in ~/.hermes/.env — Hermes leaves an unset ${VAR} as its literal placeholder text, so the server receives a header of Bearer ${BROWSERLESS_API_TOKEN} and rejects it.

What do MCP sessions cost?

Each tool call opens a browser session that consumes units based on session time, plus proxy traffic and CAPTCHA solving if used. See unit consumption for the breakdown.

Next steps​

MCP server setup

authentication options, regions, and the full tool list

Browser Agent

the stateful browser session your agent drives across turns

REST API tools

the eight stateless tools for scraping, search, and exports

Was this page helpful?