What is Hero Router?

Hero Router is the single TCP entry point for the entire Hero OS stack. Every incoming HTTP request — from a browser, CLI tool, SDK client, or AI agent — lands here first and is forwarded to the correct backend service over Unix domain sockets.

Running one router means you only need to expose, whitelist, and TLS-terminate a single network surface. Each individual service keeps its own socket-local attack surface completely off the network. You can apply a uniform IP whitelist and access policy once at the router level, and all downstream services automatically inherit it.

Unlike the rest of the Hero stack, hero_router is a single binary that collapses three roles that are normally spread across separate processes:

The same binary also hosts the reverse proxy that fans traffic out to every other service that has registered a Unix socket under $PATH_SOCKET.

Getting Started

Installation

Use the nu shell service script:

service router install # build and install binary
service router start # start the service

Running the router

# Start with automatic socket discovery (default port 9988)
service router start

# Force a clean restart
service router start --reset

The router creates two Unix sockets immediately on start:

$PATH_SOCKET/hero_router/
├── rpc.sock ← OpenRPC / JSON-RPC 2.0 (machine-callable)
└── admin.sock ← Admin dashboard + reverse proxy (browser-facing)

The TCP listener(s) (default port 9988) serve the same content as admin.sock. The bind address is auto-detected from the user’s mycelium bridge unless --bind ADDR:PORT is given — see Configuration.

Environment variables

First steps after starting

1. Open http://127.0.0.1:9988/ — the Home page shows every service that has a web UI, as coloured tiles.
2. Click Router to explore the OpenRPC service catalogue and test API methods interactively.
3. Click Admin to set up the IP whitelist and SSH authorized keys.
4. Open the Terminal tab for a browser-based nu shell session.