Hero Router

The single TCP entry point for all Hero services. Scans Unix sockets, routes HTTP traffic by URL prefix, provides service discovery, documentation, and an MCP gateway.

Quick Start

lab --start

Open the admin dashboard at http://localhost:9988.

Architecture

Internet / Browser / hero_proxy
       │
  :9988 (TCP, localhost only)
       │
  hero_router
    ├── /{service}/rpc/*    → {service}/rpc.sock
    ├── /{service}/admin/*  → {service}/admin.sock
    ├── /{service}/{web}/*  → {service}/web_{name}.sock
    ├── /rpc                → management API
    ├── /mcp                → MCP gateway
    └── /admin              → admin dashboard (same port)
       │
  Unix sockets (auto-discovered)
    ~/hero/var/sockets/
      hero_compute/rpc.sock
      hero_compute/admin.sock
      hero_proxy/rpc.sock
      hero_proc/rpc.sock
      ...

Features

• Auto-discovery — scans $HERO_SOCKET_DIR/ for service sockets
• URL prefix routing — /{service}/{socket_type}/* stripped and forwarded
• Header injection — X-Hero-Context, X-Hero-Claims, X-Forwarded-Prefix
• MCP gateway — exposes services as MCP-compatible tools for AI agents
• Admin dashboard — interactive web UI with service status
• CLI — list, scan, spec, markdown, html subcommands
• Documentation generation — Markdown and HTML from OpenRPC specs

Crate

Crate	Type	Description
hero_router	binary + library	Single binary with CLI, server, admin UI, and core library (herolib_router)

All crates were consolidated into a single binary in v0.2.0.

Sockets

All sockets under $HERO_SOCKET_DIR/hero_router/ (default: ~/hero/var/sockets/hero_router/).

Socket	Protocol	Description
rpc.sock	JSON-RPC 2.0	Management API
admin.sock	HTTP	Admin dashboard

Ports (TCP, localhost only)

Port	Description
9988	Routing entry point + admin dashboard (default)

Documentation

• Configuration — Environment variables and CLI flags
• API Reference — JSON-RPC management API
• Architecture — Routing, discovery, and request flow
• Setup — Installation and deployment
• Releasing — How to create a new release

Development

Use lab for all lifecycle operations:

lab --start    # build, install, and start all service binaries
lab --stop     # stop all service binaries
lab --status   # check status of all service binaries

Security

• TCP listeners bind to 127.0.0.1 only by default (or an explicit --address)
• Use hero_proxy for external/TLS access

Admin UI whitelist (optional)

When hero_router is exposed on a non-loopback address (e.g. the mycelium IPv6 of the host), the admin UI can be locked to specific source IPs. The whitelist is stored as a hero_proc secret — no config files.

• Storage: hero_proc secret core/ADMIN_SECRETS, value is a comma-separated list of IP addresses (IPv4 or IPv6).
• UDS (admin.sock) always bypasses — local tooling over the Unix socket is trusted.
• Fail-open: if hero_proc is unreachable, or the secret is missing/empty, the feature is disabled and all TCP connections are allowed. This keeps hero_router usable when the supervisor is down.
• Fail-closed only when configured: once ADMIN_SECRETS contains at least one valid IP, every non-matching TCP connection is silently dropped at accept time — no HTTP response, just a closed socket.
• Refresh: the running process re-reads the secret every 60 seconds, so CLI edits propagate without a restart.
• Same pattern applies to any Hero admin interface that wants whitelisting — read/write this one secret.

Manage from the CLI:

hero_router access list            # show current whitelist
hero_router access add 10.0.0.5    # add an IP (switches enforcement on)
hero_router access remove 10.0.0.5 # remove a single IP
hero_router access clear           # delete the secret (reverts to open access)

Pass --context <N> to any subcommand when operating a non-default context.

Or manage from the dashboard: open Admin in the top navbar (or go to /admin). The page shows your current source IP, the active whitelist, and buttons to add/remove/clear entries.