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)

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

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

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

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):

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

# 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

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

agent-browser install timeout — Google CDN unreachable. Skip it; use Playwright Chromium + CDP mode.
Missing shared libraries — libatk-1.0.so.0: cannot open → run Step 4.
browser_navigate timeout (60s) — Chrome not running or browser.cdp_url wrong. Run curl -s http://localhost:9222/json/version to diagnose.
Config change not taking effect — browser.cdp_url snapshotted at session start. /reset required.
Chrome crashes silently — check dmesg | tail -20 for OOM. Headless Chrome uses ~200MB RAM minimum.
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

4.0 KiB Raw Blame History