hermes-browser-playwright

Custom anti-detect Chromium browser backend for Hermes Agent — REST server wrapper + Hermes client module.

Replaces Hermes's default cloud browser backend (Browserbase) with a local Playwright-CLI REST server, enabling:

• Local-only browser automation — no external API costs
• Anti-detect Chromium — persistent fingerprints, cookies, auth across sessions
• Visible browser — watch the agent browse in real-time
• Multi-tab sessions — isolated browser contexts per task
• Persistent auth state — stay logged into sites across restarts

Architecture

Hermes Agent
    │  browser_* tool calls
    ▼
browser_playwright.py        ← Hermes client module (routes via PLAYWRIGHT_CLI_URL)
    │  HTTP REST
    ▼
browser_playwright_server.py  ← Flask REST server wrapper
    │  subprocess / JSON-RPC
    ▼
playwright-cli                ← CLI tool wrapping the anti-detect Chromium
    │
    ▼
~/.config/playwright-cli/hermes-profile/  ← Persistent browser profile (cookies, auth)

Prerequisites

• Hermes Agent installed
• playwright-cli installed and configured
• Python 3.11+
• A custom anti-detect Chromium (or standard Chromium)

Quick Start

1. Install

pip install hermes-browser-playwright

Or install from source:

git clone https://github.com/sasajib/hermes-browser-playwright.git
cd hermes-browser-playwright
pip install -e .

2. Configure playwright-cli

# Point to your custom Chromium
playwright-cli config set chromium.path /path/to/your/chromium

# Or use the default
playwright-cli config set chromium.path $(which chromium)

3. Start the REST server

# Quick start
playwright-http-server --port 9378

# Or use the launcher script (recommended — handles working directory)
cp -r skills ~/.hermes/skills/
cp scripts/playwright-browser.sh ~/.hermes/scripts/
chmod +x ~/.hermes/scripts/playwright-browser.sh
~/.hermes/scripts/playwright-browser.sh start

4. Configure Hermes

Add to your ~/.hermes/.env:

PLAYWRIGHT_CLI_URL=http://127.0.0.1:9378

That's it. Restart Hermes and browser tools will route through your local Playwright backend.

Installation Methods

Option A: Launcher Script (Recommended)

# Copy files
cp -r skills ~/.hermes/skills/
cp scripts/playwright-browser.sh ~/.hermes/scripts/
chmod +x ~/.hermes/scripts/playwright-browser.sh

# Start server
~/.hermes/scripts/playwright-browser.sh start

# Auto-start on login (add to ~/.zshrc)
echo '~/.hermes/scripts/playwright-browser.sh auto' >> ~/.zshrc

Option B: Systemd User Service

# Install systemd units
cp systemd/hermes-playwright-server.service ~/.config/systemd/user/
cp systemd/hermes.target ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now hermes-playwright-server.service

# Also enable the hermes.target for boot ordering
systemctl --user enable --now hermes.target

Option C: Docker / Custom Setup

# Run server in a container or on a remote machine
docker run -d \
  --name hermes-playwright \
  -p 9378:9378 \
  -v ~/.playwright:/root/.playwright \
  -v ~/.config/playwright-cli:/root/.config/playwright-cli \
  sasajib/hermes-browser-playwright

Then set PLAYWRIGHT_CLI_URL=http://localhost:9378 in your Hermes .env.

Configuration

Environment Variables

Variable	Default	Description
PLAYWRIGHT_CLI_URL	http://127.0.0.1:9378	REST server URL
PLAYWRIGHT_CONFIG	~/.playwright/cli.config.json	playwright-cli config path
PLAYWRIGHT_PROFILE	~/.config/playwright-cli/hermes-profile	Browser profile directory

playwright-cli Config

Edit ~/.playwright/cli.config.json:

{
  "chromium": {
    "path": "/home/user/.local/bin/chromium",
    "args": [
      "--disable-blink-features=AutomationControlled",
      "--disable-detection"
    ]
  },
  "headless": false,
  "timeout": 30000
}

Project Structure

hermes-browser-playwright/
├── src/hermes_browser_playwright/
│   ├── __init__.py
│   ├── server.py          # Flask REST server wrapper
│   └── client.py          # Hermes client module (playwright_vision, etc.)
├── skills/
│   └── SKILL.md           # Sana's Playwright guide for Hermes
├── scripts/
│   └── playwright-browser.sh  # Launcher script
├── systemd/
│   ├── hermes-playwright-server.service
│   └── hermes.target
└── patches/
    └── browser_tool.py.patch   # Optional: patch for older Hermes versions

Key Design Decisions

Why REST over direct subprocess?

1. Stateless Hermes — Hermes tool calls are stateless HTTP requests; REST server maintains the live browser session
2. Cross-platform — The REST server can run on a different machine or container
3. Simpler tool routing — browser_tool.py checks PLAYWRIGHT_CLI_URL env var and routes HTTP instead of managing subprocess lifecycle

Why playwright-cli over python-playwright?

playwright-cli is CLI-first, designed for the same use case (headless browser automation from CLI). Using it directly means we get all its features (anti-detect flags, profile management, multi-tab) without reimplementing them.

Workspace Resolution

playwright-cli resolves its .playwright-cli/ workspace relative to the current working directory. This means the REST server must run from the hermes-agent root directory (~/.hermes/hermes-agent), NOT from the user's home directory.

This is handled by:

• The playwright-browser.sh script: cd "$TOOLS_DIR" before launching
• The systemd service: WorkingDirectory=/home/user/.hermes/hermes-agent

Contributing

Contributions welcome! Please open an issue first to discuss.

1. Fork the repo
2. Create your feature branch (git checkout -b feat/my-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin feat/my-feature)
5. Open a Pull Request

License

MIT — see LICENSE.