BrowserOS + Hermes Agent Integration Guide

BrowserOS is a Chromium-based browser with a built-in Model Context Protocol (MCP) server. When paired with Hermes Agent, it lets Hermes use browser tools through a local HTTP connection. The available tools and connection details can change between BrowserOS releases, so treat the browser's MCP settings as the source of truth.

Introduction¶

What is BrowserOS?¶

BrowserOS provides browser automation capabilities such as:

When to Use BrowserOS vs Hermes Browser Tools¶

Integration Setup¶

Prerequisites¶

1. BrowserOS installed and running
2. Hermes Agent installed — MCP support is included in the standard Hermes install
3. A dedicated browser profile for agent experiments

Quick Start¶

1. Start BrowserOS and open its MCP settings page. In current releases this is available at chrome://browseros/mcp.

2. Copy the Server URL shown there. Do not assume a port from an older article or installation; the browser may change it between releases.

3. Add the copied URL to Hermes:

# ~/.hermes/config.yaml
mcp_servers:
  browseros:
    url: "<Server URL copied from chrome://browseros/mcp>"
    timeout: 120
    connect_timeout: 30

Replace the example URL with the exact URL shown by BrowserOS.

1. Start or reload Hermes:

hermes

Verification¶

Check the connection from Hermes:

hermes mcp list

Hermes registers discovered tools using the pattern mcp_<server_name>_<tool_name> (for example, mcp_browseros_navigate_page). The exact tool list depends on the BrowserOS release and your enabled connections.

Tool Categories¶

BrowserOS exposes a release-dependent set of tools. The categories below are representative examples, not a promise that every installation contains every entry.

1. Page/Tab Management¶

2. Content Extraction¶

3. Interaction¶

4. Media & Export¶

5. Window Management¶

6. Bookmarks¶

7. History¶

8. Tab Groups¶

9. Script Execution¶

10. Connect Apps¶

Practical Examples¶

Example 1: Quick Page Summary¶

Request:

"Summarize the current state of quantum computing from Wikipedia"

Tools used:

1. navigate_page → go to Wikipedia quantum computing page
2. get_page_content → extract clean markdown
3. Summarize the content

Example 2: Multi-Source Research¶

Request:

"Research the best noise-canceling headphones from 5 sources and create a comparison table"

Workflow:

1. Create workspace: create_hidden_window
2. Open 5 hidden tabs: new_hidden_page × 5
3. Navigate each: navigate_page
4. Extract: get_page_content or evaluate_script
5. Save each: write to raw/
6. Close: close_page
7. Merge: Read all raw files, create merged.csv
8. Report: Generate report.html

Example 3: Product Availability Tracking¶

Request:

"Track the availability of 'NVIDIA RTX 5090' on Amazon, Newegg, and Best Buy. Alert me when one is in stock."

Workflow:

1. Create 3 hidden tabs for each retailer
2. Navigate to product pages
3. Use evaluate_script to extract availability text
4. Save availability history to a local file
5. Compare against threshold
6. Alert user if condition met

Example 4: Form Submission¶

Request:

"Fill out the signup form at example.com/signup with test credentials"

Tools used:

1. navigate_page → go to form
2. take_snapshot → get element IDs
3. fill → fill name/email fields
4. select_option → select dropdown
5. click → submit button
6. handle_dialog → accept confirmation

Example 5: Bookmarks Management¶

Request:

"Create a bookmark folder for 'AI Research' and save these 5 URLs as bookmarks inside it"

Workflow:

1. create_bookmark → create folder
2. create_bookmark × 5 → add each URL with the folder ID

Example 6: Screenshot Walkthrough¶

Request:

"Create a step-by-step screenshot walkthrough of logging into Gmail"

Workflow:

1. new_page → navigate to Gmail
2. take_snapshot → get login elements
3. save_screenshot → capture each step
4. Continue until logged in
5. Compile into markdown with image paths

Built-in Skills¶

Some BrowserOS releases include local workflows under ~/.browseros/skills/builtin/. Treat this directory as installation-specific and inspect each workflow before enabling it:

Advanced Workflows¶

A. Deep Research (Multi-Day)¶

BrowserOS has a built-in deep-research skill:

"Research the current state of AI coding assistants. Compare at least 5 sources including GitHub, papers with code, and industry blogs. Create both an HTML report and a PDF."

Hermes will:

1. Plan 5 search queries
2. Open parallel hidden tabs (10 max)
3. Navigate, extract, save each source
4. Merge findings into findings.md
5. Generate report.html
6. Save as PDF with save_pdf

B. Product Comparison¶

Build a product comparison workflow:

1. Define products — Create a CSV with product names and URLs
2. Hidden window — Use create_hidden_window for automation
3. Parallel extraction — Open up to 10 tabs
4. Value extraction — Use evaluate_script with a selector or regex to extract the relevant value
5. Merge — Combine into comparison CSV
6. Report — Generate HTML with comparison columns and links

C. Web Monitoring¶

Set up monitoring with cron:

1. Use BrowserOS to navigate to target pages
2. Extract current state with get_page_content
3. Compare against previous saved state
4. If changes detected, alert via Hermes
5. Save new state

Example cron job:

# Check Hacker News top post every hour
0 * * * * hermes exec "check HN and save top story"

D. Connect Apps Actions¶

BrowserOS can connect to external services through its connected-apps layer:

1. discover_server_categories_or_actions — List available services
2. get_category_actions — Get actions for a service (e.g., GitHub)
3. get_action_details — Get required parameters
4. execute_action — Execute with parameters
5. handle_auth_failure — If auth fails, get auth URL

Best Practices¶

1. Always Take a Snapshot First¶

Before any automation, always:

# Get interactive elements
snapshot = take_snapshot()
# Then use the element IDs for clicks, fills, etc.

2. Save Data Incrementally¶

Never accumulate data in memory:

# GOOD: Save each page immediately
for page in pages:
    data = extract(page)
    save(f"raw/{page.slug}.json")
merge_from_files("raw/")

3. Limit Concurrent Tabs¶

Max 10 open tabs at a time:

# Process in batches of 10
for batch in chunks(urls, 10):
    tabs = [new_hidden_page(url) for url in batch]
    extract_all(tabs)
    close_all(tabs)

4. Handle Dynamic Content¶

For pages with infinite scroll or lazy loading:

# Scroll to load more content
await scroll(direction="down")

# Or use JavaScript
evaluate_script(script="window.scrollTo(0, document.body.scrollHeight)")

5. Use JavaScript for Complex Extraction¶

For nested structures (product cards, etc.):

// extract.js
const items = document.querySelectorAll(".product-card");
return JSON.stringify(
  Array.from(items).map((item) => ({
    name: item.querySelector(".title").innerText,
    value: item.querySelector(".value").innerText,
    url: item.querySelector("a").href,
  })),
);

6. Clean Up After Automation¶

Always close hidden windows and tabs:

await close_window(window_id=hidden_window_id)

7. Handle Dialogs Proactively¶

Before triggering potential dialogs:

# First, set the dialog handler
await handle_dialog(accept=True)
# Then click the element that might trigger a dialog

8. Record Source URLs¶

Every extracted data point should include its source:

product,value,source_url
NVIDIA RTX 5090,in stock,https://newegg.com/product/...

Troubleshooting¶

MCP Connection Refused¶

Problem: Failed to connect to MCP server 'browseros'

Fix:

1. Verify BrowserOS is running and open chrome://browseros/mcp.
2. Copy the current Server URL from that page.
3. Restart or reload Hermes after changing ~/.hermes/config.yaml.

Tools Not Appearing¶

Problem: Tools listed but not available

Fix:

1. Restart Hermes: hermes (new session)
2. Check config: cat ~/.hermes/config.yaml | grep -A5 mcp_servers

Page Load Timeout¶

Problem: navigate_page times out

Fix:

• Increase timeout in config:

mcp_servers:
  browseros:
    url: "<Server URL copied from chrome://browseros/mcp>"
    timeout: 180 # increased from 120

Screenshot Not Supported on Hidden Tab¶

Problem: take_screenshot fails on hidden tab

Fix:

• Use show_page first to make the tab visible:

await show_page(page_id=page_id)

Element Not Found¶

Problem: click or fill fails — element not in snapshot

Fix:

1. Wait for page to settle: evaluate_script with a small delay
2. Re-take snapshot: take_snapshot
3. Use search_dom to find element by text/CSS
4. Use scroll to bring element into view

Summary¶

BrowserOS transforms web automation from brittle scripts into reliable AI-driven workflows. Combined with Hermes Agent's memory, skills, and MCP integration, you get:

• Natural language control over any web task
• Persistent state across sessions
• Browser interaction tools for navigation, extraction, and page control
• Connect Apps for extending workflows to external services
• Built-in skills for research, extraction, monitoring

Pair BrowserOS with Hermes when you need Hermes to work through a real browser profile. Start with read-only tasks, then add write actions only after you have verified the scope and permissions of the connected tools.

Additional Resources¶

• MCP Protocol: https://modelcontextprotocol.io
• Hermes MCP: See hermes-agent skill for MCP configuration
• BrowserOS MCP documentation: https://docs.browseros.com/features/use-with-claude-code
• BrowserOS Skills: Built-in workflows at ~/.browseros/skills/builtin/

Verification¶

• Last reviewed: 2026-09-11
• Primary sources: BrowserOS MCP client documentation, Hermes MCP documentation
• Scope: Setup flow, MCP configuration shape, safety guidance, and the installed BrowserOS tool inventory were checked against the current primary documentation. The current documentation's port is illustrative; copy the installed browser's Server URL. Tool names and optional BrowserOS features remain release-dependent.