---
name: browser-setup
description: "Use when Hermes browser tools need setup on Linux."
tags: [browser, setup, cdp, playwright, china-cdn]
version: 1
created: 2026-08-07
---

# Browser Setup for Hermes

Complete pipeline to get Hermes browser tools (`browser_navigate`, `browser_snapshot`, `browser_click`, etc.) working on Linux, with special handling for environments where Google CDN is blocked.

## When to Use

- First-time browser tool setup on a Linux server
- `browser_navigate` returns timeout (60s) — browser not configured
- `agent-browser install` times out (Google CDN blocked)
- After system migration or fresh install that needs browser tools

## Quick Path (CDN accessible)

```bash
npm install -g agent-browser
agent-browser install
hermes config set browser.cdp_url 'http://localhost:9222'
# /reset in Hermes session
```

If `agent-browser install` times out, use the full pipeline below.

## Full Pipeline (CDN blocked / China)

### 1. Node.js 20.x

```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# Verify: node --version  # → v20.x
```

### 2. agent-browser CLI

```bash
sudo npm install -g agent-browser
```

Skip `agent-browser install` — it downloads Chrome from Google CDN and will time out.

### 3. Playwright + Chromium via npmmirror

```bash
pip3 install playwright
PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright \
  python3 -m playwright install chromium
```

Finds Chromium at `~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome`.

### 4. System Dependencies

Chromium needs these shared libraries (minimal Ubuntu often lacks them):

```bash
sudo apt-get install -y \
  libatk-bridge2.0-0 libatk1.0-0 libcups2 libdrm2 libgbm1 \
  libnspr4 libnss3 libxcomposite1 libxdamage1 libxfixes3 \
  libxkbcommon0 libxrandr2 libpango-1.0-0 libcairo2 libasound2
```

Symptom if missing: `error while loading shared libraries: libatk-1.0.so.0: cannot open shared object file`

### 5. Start Chrome CDP

```bash
# Clean up stale processes
pkill -9 -f "chrome" 2>/dev/null
rm -rf /tmp/chrome-hermes-data 2>/dev/null

# Launch
CHROME=$(ls ~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome | head -1)
"$CHROME" --headless=new --no-sandbox --disable-setuid-sandbox \
    --remote-debugging-port=9222 \
    --user-data-dir=/tmp/chrome-hermes-data \
    about:blank &

# Wait and verify
sleep 3
curl -s http://localhost:9222/json/version
# Expected: JSON with Browser, Protocol-Version, webSocketDebuggerUrl
```

### 6. Configure Hermes

```bash
hermes config set browser.cdp_url 'http://localhost:9222'
```

**Requires `/reset`** (new session) — `browser.cdp_url` is read at session startup.

### 7. Verify

```
browser_navigate(url='https://example.com')
# → success=true, snapshot with "Example Domain"

browser_console(expression='document.title')
# → "Example Domain"
```

## Pitfalls

1. **`agent-browser install` timeout** — Google CDN unreachable. Skip it; use Playwright Chromium + CDP mode.
2. **Missing shared libraries** — `libatk-1.0.so.0: cannot open` → run Step 4.
3. **`browser_navigate` timeout (60s)** — Chrome not running or `browser.cdp_url` wrong. Run `curl -s http://localhost:9222/json/version` to diagnose.
4. **Config change not taking effect** — `browser.cdp_url` snapshotted at session start. `/reset` required.
5. **Chrome crashes silently** — check `dmesg | tail -20` for OOM. Headless Chrome uses ~200MB RAM minimum.
6. **SPA interactive examples in sandbox iframes** — Vue/React doc sites often sandbox `Count is: 0` style demos in iframes. Clicking the counter from top-level page won't propagate. Use `browser_console` with `frame_id` for OOPIF access.

## SPA / H5 Compatibility

Browser tools fully support single-page applications. Tested with vuejs.org:

| Feature | Result |
|---------|--------|
| Initial load (JS framework) | 69 elements rendered, Vue detected |
| Client-side routing | URL change without full reload |
| Post-navigation snapshot | 130 elements (sidebar, code, switches) |
| JS errors | 0 |