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: JSON-RPC + MCP daemon, Unix socket + TCP 8884)
│ ├── hero_browser/ (bin: CLI lifecycle manager)
│ └── hero_browser_app/ (lib: Dioxus WASM UI for Hero OS)

Dependency Graph

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

Sockets & Ports

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

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 UI: Monitor sessions and activity via the hero_components admin shell

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.json | jq .

The full API is a single main domain (typed JSON-RPC 2.0). It is served on both the UDS rpc.sock and TCP 127.0.0.1:8884.

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

• POST /api/main/rpc — typed JSON-RPC 2.0 dispatch (the main domain, all 47 methods)
• GET /api/main/openrpc.json — OpenRPC document for the main domain
• GET /health.json — Health check
• GET /heroservice.json — Discovery manifest
• GET /api/domains.json, GET /api/ping — runtime metadata
• POST /mcp — MCP streamable HTTP transport (rmcp StreamableHttpService)
• GET /mcp/openrpc — copy of the OpenRPC document for MCP clients
• GET /api/sessions — List active browser sessions
• GET /api/activity, GET /api/activity/{browser_id} — recent activity log
• GET /api/sessions/{browser_id}/pages/{page_id}/stream — SSE screencast

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 UI

The admin UI for hero_browser now lives in the hero_components unified Dioxus admin shell (Sessions + Activity tabs), which monitors live browser sessions and the recent tool-call activity log.

CLI

The hero_browser binary provides lifecycle management for the server.

# 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.json | jq .

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

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

# JSON-RPC call — list active browsers (no params: send {})
curl -s --unix-socket ~/hero/var/sockets/hero_browser/rpc.sock \
 -X POST http://localhost/api/main/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"browser_list","params":{}}'

# JSON-RPC call — create a browser (struct param: wrap in {"input": {...}})
curl -s --unix-socket ~/hero/var/sockets/hero_browser/rpc.sock \
 -X POST http://localhost/api/main/rpc \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":2,"method":"browser_create","params":{"input":{"headless":true}}}'

Method names are verbatim snake_case (browser_create, browser_list, page_navigate, …) — no dots, no service prefix. Param shapes: a struct parameter is sent as {"input": {...}}, a scalar (e.g. browser_destroy) as {"browser_id": "..."}, and a no-arg method as {}. The 47-method source of truth is crates/hero_browser_server/oschema/main/90_rpc.oschema and the generated crates/hero_browser_server/openrpc/openrpc_main.json.

Documentation

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

License

Apache-2.0