# Hermes Web Browsing Ecosystem — Complete Reference

## Architecture Overview

Hermes has **two layers** of web capability:

1. **Built-in tools** (`web_search`, `web_extract`, browser tools) — model-callable, always available when configured
2. **MCP addons** — external tool servers that extend what the agent can do with web content

Both are independent and composable. You can use built-in DDGS for search + a Puppeteer MCP for rendering + the Hermes browser tools for interaction.

---

## Layer 1: Web Search Backends (8 providers)

### Search-Only

| Backend | Env Var | Free Tier | Requirement |
|---------|---------|-----------|-------------|
| **DDGS** (DuckDuckGo) | none | Unlimited | `uv pip install ddgs` — not a Hermes dep |
| **Brave Search** | `BRAVE_SEARCH_API_KEY` | 2K queries/mo | Get key at api.search.brave.com |
| **SearXNG** | `SEARXNG_URL` | Unlimited (self-hosted) | Docker: `searxng/searxng` on port 8888 + enable JSON format in settings.yml |
| **xAI (Grok)** | `XAI_API_KEY` | Paid (SuperGrok) | LLM-generated results — trust caveat |

### Search + Extract

| Backend | Env Var | Free Tier | Best For |
|---------|---------|-----------|----------|
| **Firecrawl** (default) | `FIRECRAWL_API_KEY` | 500 credits/mo | Default choice, also crawl/map/browse |
| **Tavily** | `TAVILY_API_KEY` | 1K searches/mo | AI-optimised result ranking |
| **Exa** | `EXA_API_KEY` | 1K searches/mo | Neural/semantic/content-based search |
| **Parallel** | `PARALLEL_API_KEY` | Paid | Deep research, multi-source synthesis |

### Per-Capability Split

Configure different providers for search vs extract independently:
```yaml
web:
  search_backend: "ddgs"      # free unlimited search
  extract_backend: "firecrawl" # or tavily/exa for extraction
```
When `extract_backend` is empty (`''`), `web_extract` tool is unavailable.

### Auto-Detection Order (when `web.backend` is empty)

1. `FIRECRAWL_API_KEY` or `FIRECRAWL_API_URL` → firecrawl
2. `PARALLEL_API_KEY` → parallel
3. `TAVILY_API_KEY` → tavily
4. `EXA_API_KEY` → exa
5. `SEARXNG_URL` → searxng

**xAI is NOT in auto-detection** — must be explicitly set via `web.backend: "xai"`.

### web_extract Summarization Pipeline

| Page Size | Behavior |
|-----------|----------|
| < 5,000 chars | Returned raw — no LLM call |
| 5K–500K | Single-pass summary via `auxiliary.web_extract` model (~5K output) |
| 500K–2M | Chunked: 100K-char splits → parallel summarize → synthesize |
| > 2M | Refused — hint to use smaller source |

Default auxiliary model = main chat model. To route to a cheaper model:
```yaml
auxiliary:
  web_extract:
    provider: openrouter
    model: google/gemini-3-flash-preview
    timeout: 360
```

---

## Layer 2: Browser Automation (6 modes)

| Mode | Setup | Stealth | Cost | Best For |
|------|-------|---------|------|----------|
| **Local Chromium** (agent-browser) | `npm install -g agent-browser` ✅ already installed | None | Free | Headless scraping, form filling |
| **CDP /browser connect** | CLI command in Hermes + Chrome with `--remote-debugging-port=9222` | Real browser identity | Free | Watching the agent work in your real browser, using your cookies |
| **Camofox** | Docker `jo-inc/camofox-browser` + `CAMOFOX_URL` | Firefox fingerprint spoofing | Free | Anti-detection, persistent profiles, VNC live view |
| **Browserbase** | `BROWSERBASE_API_KEY` + project ID | Residential proxies, CAPTCHA solving | Paid | Production scraping, hard targets |
| **Browser Use** | `BROWSER_USE_API_KEY` | Cloud proxies | Paid | Alternative cloud browser |
| **Firecrawl Cloud** | `FIRECRAWL_API_KEY` | Built-in scraping | 500 credits/mo | Simple browse + extract in one |

### Hybrid Routing

When a cloud provider is configured, Hermes auto-routes:
- **Public URLs** → cloud provider
- **Private/LAN URLs** (localhost, 192.168.x.x, 10.x.x.x, etc.) → auto-spawned local Chromium sidecar

Controls:
```yaml
browser:
  auto_local_for_private_urls: true   # default
  allow_private_urls: false           # if false + auto_local off, private URLs are rejected
```

### Available Browser Tools (built-in)

`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_scroll`, `browser_press`, `browser_back`, `browser_get_images`, `browser_vision` (screenshot + vision analysis), `browser_console` (JS console + eval), `browser_cdp` (raw CDP passthrough, CDP-connect only), `browser_dialog` (native JS dialog handler)

### CDP Connect

```bash
# In Hermes CLI (not gateway/Telegram/webui):
/browser connect                              # auto-detect local Chrome
/browser connect ws://host:port               # specific CDP endpoint
/browser disconnect                           # back to cloud/local mode
```

Requires a dedicated browser process with `--remote-debugging-port=9222` and a separate `--user-data-dir` to ensure the debug port actually opens.

---

## Layer 3: MCP Servers for Web Browsing

Install via `hermes mcp install <name>` or add to `~/.hermes/config.yaml` under `mcp_servers:`.

### Top MCP Servers

| MCP Server | Install | What It Does |
|-----------|---------|-------------|
| **Puppeteer** | `npx -y @anthropic/mcp-server-puppeteer` | Headless Chrome: screenshots, PDF, JS render, form fill |
| **Playwright MCP** | Various npm packages | Multi-browser (Chromium/Firefox/WebKit) automation |
| **Brave Search MCP** | `npx -y @modelcontextprotocol/server-brave-search` | Brave Search API as MCP tool |
| **Fetch MCP** | `npx -y @modelcontextprotocol/server-fetch` | Simple HTTP fetch (lighter than browser) |
| **Firecrawl MCP** | Community packages | Firecrawl browse/scrape via MCP |
| **Web Scraper MCP** | Various npm/pip packages | CSS-selector structured data extraction |

### Adding an MCP Server

```yaml
mcp_servers:
  puppeteer:
    command: "npx"
    args: ["-y", "@anthropic/mcp-server-puppeteer"]
    tools:
      include: [click, screenshot, navigate, fill]  # whitelist
      exclude: []                                     # blacklist
```

Hermes registers tools as `mcp_<server>_<tool>`. Filter per-server with `tools.include`/`tools.exclude`.

---

## Layer 4: Hermes Plugin System

### Built-in Plugin Directories (on disk, no download needed)

**`plugins/browser/`**: `browserbase`, `browser_use`, `firecrawl` — cloud browser provider implementations

**`plugins/web/`**: `brave_free`, `ddgs`, `exa`, `firecrawl`, `parallel`, `searxng`, `tavily`, `xai` — web search/extract provider implementations

### Custom Plugins
User plugins go in `~/.hermes/plugins/`. They can add tools, lifecycle hooks, CLI commands, and MCP servers. Building a plugin requires implementing the Hermes plugin ABCs — see the Developer Guide.

---

## Common Configurations by Use Case

### 1. Free, zero-api-key (already set up here)
```bash
uv pip install ddgs
hermes config set web.search_backend ddgs
# Browser: use /browser connect or agent-browser (already installed)
```

### 2. Free search + paid extract
```bash
hermes config set web.search_backend ddgs
hermes config set web.extract_backend firecrawl
# Add FIRECRAWL_API_KEY to ~/.hermes/.env
```

### 3. Self-hosted everything
```bash
# Docker SearXNG on :8888
# Camofox on :9377 for anti-detection browsing
hermes config set web.search_backend searxng
# Add SEARXNG_URL=http://localhost:8888 to ~/.hermes/.env
# Add CAMOFOX_URL=http://localhost:9377 to ~/.hermes/.env
```

### 4. Heavy production (cloud browser + AI search)
```bash
# Browserbase + Tavily
hermes config set web.search_backend tavily
hermes config set web.extract_backend tavily
# Add BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, TAVILY_API_KEY to .env
```