Hero Browser

Headless browser automation with MCP protocol support and Rhai scripting.

Architecture

Multi-crate workspace following Hero OS conventions:

hero_browser/
├── Cargo.toml
├── crates/
│ ├── hero_browser_sdk/ (lib: types, browser pool, activity log)
│ ├── hero_browser_server/ (bin: MCP daemon, OpenRPC, Unix socket + TCP 8884)
│ ├── hero_browser/ (bin: CLI client, script runner)
│ ├── hero_browser_admin/ (bin: Axum admin dashboard)
│ └── hero_browser_rhai/ (lib: Rhai scripting bindings)

Dependency Graph

hero_browser_sdk (no internal deps)
 ↑ ↑ ↑ ↑
 server CLI admin rhai

Sockets & Ports

Component	Socket	TCP Port
Server (MCP)	$PATH_SOCKET/hero_browser/rpc.sock	8884 (env: HERO_BROWSER_MCP_PORT)
Admin UI	$PATH_SOCKET/hero_browser/admin.sock	—

PATH_SOCKET defaults to ~/hero/var/sockets.

Important: The MCP server listens on both the Unix socket and TCP port 8884. The TCP port is required for Claude Code MCP integration (claude mcp add --transport http hero_browser http://localhost:8884/mcp). Do not remove the TCP listener.

Features

• MCP Server: Control browsers via Model Context Protocol (HTTP transport)
• Rhai Scripting: Write automation scripts with a simple scripting language
• Shebang Support: Run scripts directly with #!/usr/bin/env hero_browser
• Visible Mode: Debug scripts by watching the browser in action with --show flag
• Admin Dashboard: Monitor sessions and activity in real-time

Quick Start

# Install all binaries and register with hero_proc
lab service browser --install
lab service browser --start

# Check status
lab service browser --status

# Stop
lab service browser --stop

Requirements

• Google Chrome (macOS) or Chromium (Linux)
• Rust 1.82+

MCP Server

The hero_browser_server binary provides a Model Context Protocol server for Claude Code integration.

# Start (managed by lab)
lab service browser --start

# Verify health
curl -s --unix-socket ~/hero/var/sockets/hero_browser/rpc.sock \
 http://localhost/health | jq .

API endpoints on rpc.sock (and TCP 8884):

• POST /rpc — JSON-RPC 2.0 / OpenRPC dispatch
• GET /openrpc.json — OpenRPC document
• GET /health — Health check
• GET /.well-known/heroservice.json — Discovery manifest
• GET /api/sessions — List active browser sessions
• GET /api/activity — Recent MCP activity log
• POST /mcp — MCP streamable HTTP transport

Claude Code Configuration

The server auto-configures on startup. Manual setup (or to re-register after a restart):

claude mcp remove hero_browser
claude mcp add --scope user --transport http hero_browser http://localhost:8884/mcp

Admin Dashboard

The hero_browser_admin binary provides a web dashboard for monitoring browser sessions and activity.

Served from $PATH_SOCKET/hero_browser/admin.sock and proxied through hero_router at /<service>/admin/.

CLI

The hero_browser binary provides a CLI for running Rhai scripts.

# Run a Rhai script
hero_browser script.rhai

# Run with visible browser
hero_browser --show script.rhai

Smoke Tests

# Health check
curl -s --unix-socket ~/hero/var/sockets/hero_browser/rpc.sock \
 http://localhost/health | jq .

# OpenRPC doc
curl -s --unix-socket ~/hero/var/sockets/hero_browser/rpc.sock \
 http://localhost/openrpc.json | jq '.methods[].name'

# Discovery manifest
curl -s --unix-socket ~/hero/var/sockets/hero_browser/rpc.sock \
 http://localhost/.well-known/heroservice.json | jq .

# JSON-RPC ping
curl -s --unix-socket ~/hero/var/sockets/hero_browser/rpc.sock \
 -X POST http://localhost/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"system.ping","params":{}}'

Available Rhai Functions

Browser Lifecycle

• browser_create() - Create new browser, returns browser_id
• browser_create_with_options(opts) - Create with options
• browser_destroy(browser_id) - Close browser
• browser_list() - List active browser IDs

Page Operations

• page_create(browser_id) - Create new page
• page_navigate(browser_id, page_id, url) - Navigate to URL
• page_navigate_back/forward(browser_id, page_id) - History navigation
• page_url/content/title(browser_id, page_id) - Get page info
• page_screenshot(browser_id, page_id) - Take screenshot (base64)
• page_screenshot_save(browser_id, page_id, path) - Save screenshot
• page_close(browser_id, page_id) - Close page

Element Interaction

• element_click(browser_id, page_id, selector) - Click element
• element_type(browser_id, page_id, selector, text) - Type text
• element_hover(browser_id, page_id, selector) - Hover
• element_wait(browser_id, page_id, selector, timeout_ms) - Wait for element
• element_drag_drop(browser_id, page_id, source, target) - Drag and drop

JavaScript, Cookies, Network, Accessibility

• js_execute(browser_id, page_id, script) - Execute JavaScript
• cookies_get/set/delete(...) - Cookie management
• network_install/requests/clear(...) - Network monitoring
• accessibility_tree/snapshot(...) - Accessibility info
• console_install/messages/clear(...) - Console capture
• viewport_set/set_mobile(...) - Viewport control
• key_press(browser_id, page_id, key) - Keyboard input
• dialog_accept/dismiss(...) - Dialog handling

Documentation

• Architecture - System design
• API Reference - Full API documentation
• Scripting Guide - Writing automation scripts
• MCP Quick Start - 5-minute setup
• MCP Integration Guide - Complete reference

License

Apache-2.0