Hero Router

A CLI tool and web dashboard for discovering and documenting RPC services.

Hero Router scans your Hero OS service ecosystem, fetches OpenRPC specifications, generates documentation, and provides an interactive web UI for exploring your services.

Features

• Auto-discovery — scan ~/hero/var/sockets/ for live RPC services
• Web Dashboard — interactive two-pane interface with Bootstrap 5 styling
• CLI Tool — inspect services, generate docs, list services without running a server
• Manual imports — add any OpenRPC spec by local file path or HTTP(S) URL
• Documentation generation — produce Markdown and HTML docs
• JSON-RPC 2.0 API — all data operations available via RPC
• MCP Gateway — expose each healthy service as MCP-compatible endpoint
• Dark/Light theme — responsive design with theme toggle

Architecture

hero_router/
├── Cargo.toml                         # workspace root
├── Makefile
├── buildenv.sh
├── scripts/
│   ├── build_lib.sh
│   └── download-assets.sh
├── crates/
│   ├── hero_router/                # core library (herolib_router)
│   ├── hero_router_server/         # JSON-RPC backend + TCP routing entry point
│   ├── hero_router_sdk/            # generated OpenRPC client
│   ├── hero_router_ui/             # web admin dashboard
│   └── hero_router_examples/       # SDK usage examples

Crate	Type	Description
herolib_router	library	Core logic: scanner, cache, probe, doc generation
hero_router_server	binary	JSON-RPC backend, TCP routing entry point, CLI subcommands
hero_router_sdk	library	Generated typed client from OpenRPC spec
hero_router_ui	binary	Web admin dashboard
hero_router_examples	examples	SDK usage examples

Sockets & Ports

Component	Unix Socket	TCP Port	Purpose
hero_router_server	~/hero/var/sockets/hero_router_server.sock	9998	JSON-RPC backend + routing entry point
hero_router_ui	~/hero/var/sockets/hero_router_ui.sock	9997	Web admin dashboard

• hero_router_server always binds TCP — it is the single TCP entry point that proxies traffic from /<service>/rpc to per-service Unix sockets. It also exposes CORS headers so browser clients at any origin can call /rpc directly.
• hero_router_ui provides the admin web interface and can run independently of the server.

Quick Start

# Clone and build
git clone ssh://forge.ourworld.tf/lhumina_code/hero_router.git
cd hero_router
make install

# Run both server and UI
make run

# Or run in debug mode
make rundev

Running with a custom port

# Server on a non-default port
hero_router_server --port 8998

# UI on a non-default port
hero_router_ui --port 8997

CLI Usage

# List discovered services
hero_router_server list

# Scan for services
hero_router_server scan --verbose

# Fetch a service spec
hero_router_server spec hero_books

# Generate Markdown documentation
hero_router_server markdown hero_books --output docs.md

# Generate HTML documentation
hero_router_server html hero_books --output docs.html

JSON-RPC API

The server is accessible at http://127.0.0.1:9998/rpc (TCP) or via its Unix socket. CORS is enabled so browser clients at any origin can POST directly.

Method	Description
router.services	List all services
router.service	Get single service by ID
router.scan	Trigger re-scan
router.openrpc	Get cached OpenRPC spec
router.markdown	Generate Markdown docs
router.html	Generate HTML docs
router.status	Health and stats
router.add	Register manual spec
router.remove	Remove manual spec
router.mcp_logs	MCP gateway logs
router.mcp_logs_clear	Clear MCP logs
admin.health	Simple health check
rpc.discover	Return this OpenRPC spec

Configuration

Setting	Default	CLI Flag	Env Var
Server TCP port	9998	--port (hero_router_server)	ROUTER_SERVER_PORT
UI TCP port	9997	--port (hero_router_ui)	ROUTER_UI_PORT
Socket directory	~/hero/var/sockets	—	HERO_SOCKET_DIR
Refresh interval	30 seconds	—	ROUTER_REFRESH
Probe timeout	3 seconds	—	ROUTER_PROBE_TIMEOUT

Building

make build       # Build release binaries
make check       # Fast code check
make test        # Run tests
make lint        # Run clippy
make install     # Build and install to ~/hero/bin
make clean       # Remove build artifacts

Security

• TCP listeners are 127.0.0.1 only (never 0.0.0.0)
• No authentication required (localhost-only access)
• All OpenRPC text is HTML-escaped by Askama
• Router only calls rpc.discover — never executes arbitrary methods

License

See LICENSE file in repository root.