Hero Browser

Headless browser automation with MCP protocol support.

Architecture

Multi-crate workspace following Hero OS conventions:

hero_browser/
├── Cargo.toml
├── crates/
│ ├── hero_browser_core/ (lib: browser pool, page handle, activity log)
│ ├── hero_browser_sdk/ (lib: auto-generated OpenRPC client)
│ ├── hero_browser_server/ (bin: MCP daemon, OpenRPC, Unix socket + TCP 8884)
│ ├── hero_browser/ (bin: CLI lifecycle manager)
│ ├── hero_browser_admin/ (bin: Axum admin dashboard)
│ └── hero_browser_app/ (lib: Dioxus WASM UI for Hero OS)

Dependency Graph

hero_browser_core (lib: browser pool, types, activity log)
 ↑ ↑ ↑ ↑
 server CLI admin app

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)
• 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.96+

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 lifecycle management for the server and admin components.

# Start/stop services via hero_proc
hero_browser --start
hero_browser --stop

# Check server health
hero_browser health

# List active browsers
hero_browser list

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":"rpc.health","params":{}}'

Documentation

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

License

Apache-2.0