Hermes Agent
Hermes Agent is Nous Research's open-source AI agent. Use Browserless as the Hermes Agent browser: run Hermes' built-in browser tools on Browserless cloud browsers with the Browserless plugin for Hermes, add scraping and agent tools with the Browserless MCP server, or use both. Either way, one API token gives your agent a cloud browser with stealth, residential proxies, and captcha solving, with no local Chrome to manage.
- A Browserless API token from your account dashboard
- Browserless plugin: Hermes Agent 0.21.6 or later, plus Node.js (Hermes drives the browser with the
agent-browserCLI) - Browserless MCP server: Hermes Agent installed with MCP support (included in the standard install script)
Two ways to use Browserless with Hermes Agent
The Browserless plugin makes Hermes' own browser tools run on Browserless, while the Browserless MCP server adds Browserless' scraping and agent tools to Hermes. Pick the plugin for step-by-step browsing and the MCP server for one-shot scraping and crawling.
| Browserless plugin | Browserless MCP server | |
|---|---|---|
| What it does | Runs Hermes' built-in browser tools on Browserless | Adds Browserless tools (browserless_smartscraper, browserless_agent, and more) |
| Best for | Agents that browse step by step: logins, forms, multi-page tasks | One-shot scraping and crawling, exports, letting Browserless' agent run a flow |
| Setup | hermes plugins install browserless plus 2 config lines | mcp_servers entry in config.yaml |
| Stealth, proxies, captchas | Settings in ~/.hermes/.env | Built into the tools |
You can use both together: the plugin for Hermes' browser, the MCP server for scraping tools. They share the same BROWSERLESS_TOKEN.
To install the Browserless plugin in Hermes Agent, run these three commands, then add BROWSERLESS_TOKEN to ~/.hermes/.env:
hermes plugins install browserless --enable
hermes config set browser.cloud_provider browserless
hermes config set browser.backend off
Option 1: Browserless plugin for Hermes Agent
The Browserless plugin is a Hermes browser provider that runs Hermes' built-in browser tools (navigate, snapshot, click, type, screenshot) on a Browserless cloud browser instead of local Chrome. It's listed in the Hermes plugin catalog and maintained by Browserless.
The plugin adds no new tools. Your agent keeps using the browser tools Hermes already has, so existing prompts and skills work unchanged. What changes is the browser behind them:
- Stealth on by default. The browser hides
navigator.webdriverand the "HeadlessChrome" user agent. See stealth mode. - Optional residential proxy, captcha solving, and ad blocking. Each is one setting in
~/.hermes/.env. - Built for long agent tasks. The plugin reconnects to the same browser and page after network drops. If a browser reaches your plan's maximum session time, Hermes gets a fresh browser automatically. Browsers close when the task ends, on Ctrl+C, or when Hermes exits.
- One Hermes task = one Browserless browser. Each task counts once toward your plan's concurrent-browser limit.
- Works on the free plan, including stealth, residential proxy, and captcha solving.
Install the Browserless plugin for Hermes Agent
Install and enable the plugin, then make it Hermes' browser provider:
hermes plugins install browserless --enable
hermes config set browser.cloud_provider browserless
hermes config set browser.backend off
browser.backend off makes Hermes use its built-in browser tools. Without it, Hermes' Browser Use mode takes over when uvx or browser-use is on your PATH, and the plugin isn't used. Start a new Hermes session after installing.
Hermes drives the browser with the agent-browser CLI. If it isn't installed, install it globally:
npm install -g agent-browser
Add your Browserless API token
The plugin reads your token from ~/.hermes/.env. Keep it there rather than in chat or a committed config file:
# Add to ~/.hermes/.env
BROWSERLESS_TOKEN=YOUR_API_TOKEN_HERE
Run a browser task on Browserless
Ask Hermes to open a page. The -t browser flag makes Hermes use its browser tools (and so Browserless) rather than its web search tools:
hermes -t browser -z 'Open https://news.ycombinator.com and tell me the top 3 story titles'
Hermes replies with the three story titles. Use single quotes in zsh, because ! inside double quotes triggers history expansion. To confirm the browser ran on Browserless and not locally, see Troubleshoot the Browserless plugin.
Enable residential proxies and captcha solving in Hermes
All plugin settings go in ~/.hermes/.env. Stealth is on by default. Everything else is opt-in:
| Setting | Default | What it does |
|---|---|---|
BROWSERLESS_STEALTH | true | Stealth browser: hides navigator.webdriver and the "HeadlessChrome" user agent |
BROWSERLESS_PROXY=residential (+ BROWSERLESS_PROXY_COUNTRY=us) | off | Routes traffic through a residential IP, the same IP for the whole session. Uses more units |
BROWSERLESS_SOLVE_CAPTCHAS | false | Auto-solves detected captchas. Works best with the residential proxy. The widget may still look unticked; submit the form normally |
BROWSERLESS_BLOCK_ADS | false | Blocks ads and trackers |
BROWSERLESS_BASE_URL | SFO | Region endpoint, for example https://production-lon.browserless.io |
BROWSERLESS_MUX_LOG | unset | File path for a connection log, for troubleshooting |
For sites that block datacenter IPs or show captchas, turn on the residential proxy and captcha solving together:
# Add to ~/.hermes/.env
BROWSERLESS_PROXY=residential
BROWSERLESS_PROXY_COUNTRY=us
BROWSERLESS_SOLVE_CAPTCHAS=true
Browserless solves the captcha on its side as soon as it's detected, so the agent doesn't need to wait or click the widget. See residential proxies and captcha solving for how each works.
Troubleshoot the Browserless plugin
If the plugin can't start a Browserless session, Hermes silently falls back to a local browser. To see which browser Hermes used, set a connection log and check it after a task:
# Add to ~/.hermes/.env
BROWSERLESS_MUX_LOG=/tmp/browserless.log
create_session ... upstream=reconnect options=stealthmeans Browserless is in use.create_session ... FAILED: <reason>explains why it isn't, for example a wrong token or your plan's concurrent-browser limit.
A few behaviors to expect:
- Localhost and LAN URLs open in a local browser. Hermes routes them there because a cloud browser can't reach your machine.
- Passwords: Hermes' agent won't type passwords itself. Store them with
hermes vault addand Hermes fills them from the vault. - Heavily protected sites can still block automated browsing, even with stealth, a residential proxy, and captcha solving.
Option 2: Browserless MCP server for Hermes Agent
The Browserless MCP server adds Browserless tools to Hermes, such as browserless_smartscraper for scraping protected pages and browserless_agent for multi-step browser flows. Use it when you want Browserless to do the scraping, crawling, or browsing in one tool call instead of Hermes driving a browser step by step.
browserless_smartscraperruns cascading strategies on every request: direct fetch, then proxy, then headless browser, then captcha solving, until the content returns.browserless_agentcan preserve cookies and page state through logins, multi-step forms, and pagination. In v1.33.0+, multi-call sessions require first-call opt-in: setkeepSessionAlive: true, then echo the returnedsessionIdon later calls.- The browsers run on Browserless' 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 fourteen tools covering scraping, search, crawling, exports, Lighthouse audits, custom Puppeteer functions, and account usage.
If you also want Hermes' own browser tools to get stealth, proxies, and captcha solving, add the Browserless plugin. With it, the built-in browser runs on Browserless too.
Step 1: Add the Browserless MCP server to your Hermes 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_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_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. If you also use the plugin, this is the same BROWSERLESS_TOKEN line, so add it once.
Step 2: Verify the Browserless MCP 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: Scrape a page with the Browserless MCP tools
Give Hermes a scraping or browsing task and name the Browserless tools:
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 MCP tools load
The server exposes fourteen tools. If you want a smaller surface, use Hermes' tool filtering to whitelist just the ones you need:
mcp_servers:
browserless:
url: "https://mcp.browserless.io/mcp"
headers:
Authorization: "Bearer ${BROWSERLESS_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
How do I use Browserless with Hermes Agent?
Install the Browserless plugin for Hermes, the Browserless MCP server, or both. The plugin runs Hermes' built-in browser tools on Browserless: run hermes plugins install browserless --enable, hermes config set browser.cloud_provider browserless, and hermes config set browser.backend off, then add BROWSERLESS_TOKEN to ~/.hermes/.env. The MCP server adds Browserless scraping and agent tools through an mcp_servers entry in ~/.hermes/config.yaml.
What's the difference between the Browserless plugin and the Browserless MCP server for Hermes?
The Browserless plugin changes which browser Hermes' existing browser tools use, while the Browserless MCP server gives Hermes new Browserless tools. With the plugin, Hermes navigates, clicks, and types step by step in a Browserless cloud browser, which suits logins, forms, and multi-page tasks. With the MCP server, Hermes calls tools like browserless_smartscraper and browserless_agent that do the scraping, crawling, or browsing in one call.
Can I use the Browserless plugin and the MCP server at the same time?
Yes. The plugin runs Hermes' built-in browser on Browserless, and the MCP server adds Browserless scraping tools alongside it. Both read the same BROWSERLESS_TOKEN from ~/.hermes/.env.
Does the Browserless plugin for Hermes work on the free plan?
Yes. The Browserless plugin for Hermes works on the Browserless free plan, including stealth, residential proxy, and captcha solving. Each Hermes task uses one browser and consumes units like any other session, so check pricing for your plan's units and concurrency limit.
How do I enable residential proxies or captcha solving in Hermes?
With the Browserless plugin, add BROWSERLESS_PROXY=residential (optionally BROWSERLESS_PROXY_COUNTRY=us) and BROWSERLESS_SOLVE_CAPTCHAS=true to ~/.hermes/.env, then start a new Hermes session. Captcha solving works best with the residential proxy, and the residential proxy uses more units. With the Browserless MCP server, no setting is needed: browserless_smartscraper escalates to a proxy and captcha solving on its own when a page blocks it.
How do I know Hermes is actually using Browserless?
Set BROWSERLESS_MUX_LOG=/tmp/browserless.log in ~/.hermes/.env and check the log after a browser task. A line with create_session ... upstream=reconnect options=stealth means Hermes used Browserless; create_session ... FAILED: <reason> means it didn't, and why. This matters because Hermes falls back to a local browser silently when the plugin can't start a Browserless session.
Why is Hermes using a local browser instead of Browserless?
Hermes falls back to a local browser when the Browserless plugin can't start a session, most often because BROWSERLESS_TOKEN is missing or wrong, or your plan's concurrent-browser limit is reached. Hermes also opens localhost and LAN URLs in a local browser on purpose, because a cloud browser can't reach your machine. Check that the plugin is enabled, browser.cloud_provider is browserless, and browser.backend is off, then use BROWSERLESS_MUX_LOG to see the failure reason.
Can I point Hermes' /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. To run Hermes' browser on Browserless, install the Browserless plugin and run hermes config set browser.cloud_provider browserless instead.
Hermes doesn't list any Browserless MCP 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_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_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.