Operator FAQ

How do I find my router’s IP?

By default hero_router serve resolves its bind address via a layered chain (HERO_MYCELIUM_IP env → ~/hero/cfg/hero_cfg.toml [mycelium].ipv6_address → getifaddrs scan of br-$USER → 127.0.0.1) and logs the chosen source at startup. Look for the default bind source: line and the tcp : entry in the startup banner.

Override with --bind ADDR:PORT (repeatable; pass :9988 for the loopback shorthand). If no --bind is given AND no mycelium signal is found, the router falls back to 127.0.0.1:9988. Passing zero TCP listeners (legacy --port 0 without --address) means the router is reachable only through the two Unix sockets under $PATH_SOCKET.

How do I restart the router?

It depends on how the router was launched:

• Shell — Ctrl-C and re-run the binary.
• hero_proc job — use the hero_proc CLI or dashboard to stop and re-create the job, or call job.restart from the SDK.
• systemd — systemctl restart hero-router.service.

Restarts are safe: the router holds no persistent state other than the manual_sources.json file on disk and the service cache, which is rebuilt from a fresh scan within one refresh_interval_secs of startup.

What if a service does not appear in the dashboard?

Walk through this checklist:

1. Is the service writing its socket under $PATH_SOCKET? The router scans only that tree.
2. Is the filename one of rpc.sock, admin.sock, rest.sock, openapi.sock, or web_<name>.sock? Other filenames are ignored.
3. Is the service directory name one of the reserved first-segment names? If so, rename it — the router will never proxy to it.
4. Wait up to 30 seconds for the next scan, or restart the router to force an immediate scan at startup.
5. Check reachability directly:

curl --unix-socket $PATH_SOCKET/<svc>/rpc.sock http://localhost/health

6. Look at the Router tab’s log pane. Failed probes and routing errors are written there with the exact path and the upstream response.

Why does a proxied service return 404?

The <webname> segment is the socket stem, not an arbitrary alias. /hero_proc/admin/... works because there is a file called admin.sock in hero_proc’s directory. Check the list of discovered sockets on the Router tab.

Where do I report a bug?

File issues in the Forgejo repository for this router. Include the exact version (hero_router --version), your OS, and the commands you ran. Include RUST_LOG=debug output when a scan or probe misbehaves.

Further Reading

• CLAUDE.md at the repository root — dual-socket architecture and the list of reserved first-segment names.
• hero_sockets skill — the wider socket naming convention that every Hero service follows.
• hero_ui_whitelists skill — the ADMIN_SECRETS key format shared with other Hero admin UIs.
• hero_proc_ui terminal contract — the tty: true + PTY WebSocket endpoint that the Terminal tab proxies.
• src/config.rs — authoritative reference for every tunable: PATH_SOCKET, ROUTER_PORT, scan interval, probe timeout, manifest path, context identifier.