Hero Browser

Headless browser automation with MCP protocol support and Rhai scripting.

Architecture

Multi-crate workspace following Hero OS best practices:

hero_browser_mcp/
├── Cargo.toml              (workspace root)
├── Makefile                (orchestration)
├── crates/
│   ├── hero_browser_sdk/    (lib: types, browser pool, activity log)
│   ├── hero_browser_server/ (bin: MCP daemon, REST API, Unix socket)
│   ├── hero_browser/        (bin: CLI client, health check, script runner)
│   ├── hero_browser_ui/     (bin: Axum HTTP admin dashboard)
│   └── hero_browser_rhai/   (lib: Rhai scripting bindings)

Dependency Graph

hero_browser_sdk  (no internal deps)
     ↑         ↑          ↑           ↑
     |         |          |           |
  server     CLI         UI        rhai

Sockets & Ports

Component	Socket	TCP Port
Server (MCP)	$HERO_SOCKET_DIR/hero_browser_server/rpc.sock	8884 (env: HERO_BROWSER_MCP_PORT)
Admin UI	$HERO_SOCKET_DIR/hero_browser_ui/ui.sock	—

HERO_SOCKET_DIR 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

# Build all binaries
make build

# Run server + health check + UI (full orchestration)
make run

# Run only the MCP server (port 8884)
make run-server

# Run with visible browser windows
make run-server-show

# Run only the admin UI (port 8885)
make run-ui

# Health check
hero_browser health

Installation

Build from Source

git clone https://forge.ourworld.tf/lhumina_code/hero_browser
cd hero_browser
make build
make install   # installs to ~/hero/bin/

Requirements

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

MCP Server

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

# Start MCP server (auto-configures with Claude Code)
hero_browser_server --port 8884

# With visible browsers
hero_browser_server --show --port 8884

API endpoints:

• POST /mcp - MCP protocol endpoint (streamable HTTP)
• GET /api/sessions - List active browser sessions
• GET /api/activity - Recent MCP activity log
• GET /api/activity/{browser_id} - Session-specific activity

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_ui binary provides a web dashboard for monitoring.

hero_browser_ui --port 8885 --server-url http://localhost:8884

Open http://localhost:8885/ to see live sessions, activity logs, and stats.

CLI

The hero_browser binary provides a CLI for scripts and health checks.

# Run a Rhai script
hero_browser script.rhai

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

# Check server health
hero_browser health

Available 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