Hero Browser

Headless browser automation with MCP protocol support and Rhai scripting.

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
• Dual Mode: Run in headless mode for efficiency or visible mode for debugging

Installation

Quick Install (Recommended)

Install the pre-built binary with a single command:

curl -sSL https://forge.ourworld.tf/lhumina_code/hero_browser/raw/main/scripts/install.sh | bash

Or download and run the installer manually:

curl -O https://forge.ourworld.tf/lhumina_code/hero_browser/raw/main/scripts/install.sh
chmod +x install.sh
./install.sh

The installer will:

• Detect your platform (Linux x86_64 or macOS ARM64)
• Download the appropriate binary to ~/hero/bin/
• Offer to install Google Chrome if not present
• Add the install directory to your PATH

Manual Download

Download the binary directly for your platform:

# Linux (x86_64)
curl -OJ https://forge.ourworld.tf/api/packages/lhumina_code/generic/hero-browser/dev/hero-browser-linux-amd64
chmod +x hero-browser-linux-amd64
mv hero-browser-linux-amd64 ~/hero/bin/hero-browser

# macOS (Apple Silicon)
curl -OJ https://forge.ourworld.tf/api/packages/lhumina_code/generic/hero-browser/dev/hero-browser-darwin-arm64
chmod +x hero-browser-darwin-arm64
mv hero-browser-darwin-arm64 ~/hero/bin/hero-browser

# Fix macOS code signing (required on macOS)
xattr -cr ~/hero/bin/hero-browser
codesign --force --sign - ~/hero/bin/hero-browser

Build from Source

For developers who want to build from source:

git clone https://forge.ourworld.tf/lhumina_code/hero_browser
cd hero-browser
./install.sh   # Install dependencies (Rust, Chrome)
./build.sh     # Build and install to ~/hero/bin/

Requirements

• Google Chrome (macOS) or Chromium (Linux)
• Supported platforms:
  • Linux x86_64 (amd64)
  • macOS ARM64 (Apple Silicon)

Quick Start

# Build and install
./build.sh

# Run a script (headless)
hero-browser scripts/surf_test.rhai

# Run with visible browser
hero-browser --show scripts/surf_test.rhai

# Start MCP server
hero-browser --mcp

# Start MCP server on custom port
hero-browser --mcp --port 8080

Visible Browser Mode

Debug your scripts by watching the browser in action:

# Watch the browser as your script runs
hero-browser --show scripts/my_script.rhai

# With shebang
chmod +x my_script.rhai
./my_script.rhai                    # runs headless
./my_script.rhai --show             # ERROR: can't pass args with shebang

# Instead, use this shebang:
#!/usr/bin/env hero-browser --show

In visible mode, you'll see:

• The browser window open
• Pages navigate
• Elements being clicked
• Text being typed
• Screenshots being captured

This is essential for debugging when automation doesn't work as expected.

Shebang Usage

Create executable scripts:

#!/usr/bin/env hero-browser

let browser_id = browser_create();
let page_id = page_create(browser_id);

page_navigate(browser_id, page_id, "https://example.com");
sleep(2000);

let title = page_title(browser_id, page_id);
println("Title: " + title);

browser_destroy(browser_id);

chmod +x script.rhai
./script.rhai                       # runs headless

# For visible mode, modify the shebang:
#!/usr/bin/env hero-browser --show

MCP Server

Start the MCP server for Claude Code integration:

hero-browser --mcp

Configure Claude Code:

claude mcp add hero-browser --transport http http://localhost:4829/mcp

The server automatically registers itself with Claude Code if available.

Available Functions

Browser Lifecycle

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

Page Operations

• page_create(browser_id) - Create new page, returns page_id
• page_navigate(browser_id, page_id, url) - Navigate to URL
• page_navigate_back(browser_id, page_id) - Navigate back in history
• page_navigate_forward(browser_id, page_id) - Navigate forward in history
• page_url(browser_id, page_id) - Get current page URL
• page_content(browser_id, page_id) - Get page HTML
• page_title(browser_id, page_id) - Get page title
• page_screenshot(browser_id, page_id) - Take screenshot (base64)
• page_screenshot_save(browser_id, page_id, path) - Take and save screenshot to file
• 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 into element
• element_hover(browser_id, page_id, selector) - Hover over element
• element_wait(browser_id, page_id, selector, timeout_ms) - Wait for element to appear
• element_drag_drop(browser_id, page_id, source_selector, target_selector) - Drag and drop between elements

Keyboard Input

• key_press(browser_id, page_id, key) - Press a key (Enter, Escape, Tab, Space, ArrowUp/Down/Left/Right, etc.)

Dialog Handling

• dialog_accept(browser_id, page_id) - Accept/OK a dialog
• dialog_accept_with_text(browser_id, page_id, text) - Accept prompt dialog with text
• dialog_dismiss(browser_id, page_id) - Dismiss/Cancel a dialog

Console Messages

• console_install(browser_id, page_id) - Start capturing console messages (call first)
• console_messages(browser_id, page_id) - Get captured console messages as JSON
• console_clear(browser_id, page_id) - Clear captured console messages

Viewport & Device

• viewport_set(browser_id, page_id, width, height) - Set viewport size
• viewport_set_mobile(browser_id, page_id, width, height, scale) - Set mobile viewport with device scale

Cookies

• cookies_get(browser_id, page_id) - Get cookies as string
• cookies_get_all(browser_id, page_id) - Get all cookies as JSON
• cookies_set(browser_id, page_id, name, value) - Set a cookie
• cookies_delete(browser_id, page_id, name) - Delete a cookie

File Upload

• file_upload(browser_id, page_id, selector, file_path) - Upload file to input element

Network Monitoring

• network_install(browser_id, page_id) - Start capturing network requests (call first)
• network_requests(browser_id, page_id) - Get captured network requests as JSON
• network_clear(browser_id, page_id) - Clear captured network requests

Accessibility

• accessibility_tree(browser_id, page_id) - Get full accessibility tree as JSON
• accessibility_snapshot(browser_id, page_id) - Get interactive elements snapshot as JSON

JavaScript

• js_execute(browser_id, page_id, script) - Execute JavaScript and return result

Logging & Utilities

• println(text) - Print to console
• log(text) - Log info message
• debug(text) - Log debug message
• sleep(ms) - Wait for milliseconds
• save_base64_to_file(data, path) - Save base64 data (like screenshots) to file

Documentation

• Architecture - System design
• API Reference - Full API documentation
• Scripting Guide - Writing automation scripts
• MCP Instructions - MCP server setup
• Visible Browser - Debug with visible browser

License

Apache-2.0