Hero Services

Service orchestrator for the Hero OS ecosystem.

Hero Services manages the lifecycle of all Hero services — building, installing, starting, stopping, and monitoring them via a unified JSON-RPC interface over Unix sockets.

Architecture

hero_services_sdk        (library: types + async Unix socket client)
     ↑         ↑          ↑           ↑
     |         |          |           |
  server     CLI         UI        rhai

Crate	Type	Purpose
hero_services_sdk	library	Types, RPC client, shared protocol
hero_services_server	binary	Daemon, JSON-RPC over Unix socket
hero_services	binary	CLI client using SDK
hero_services_ui	binary	Axum admin panel using SDK
hero_services_rhai	library	Rhai scripting bindings

Quick Start

git clone ssh://git@forge.ourworld.tf/lhumina_code/hero_zero.git
cd hero_zero
make run

Make Targets

make run           # Build (debug) and run server + UI (user profile)
make admin         # Run with admin profile
make beta          # Run with beta profile
make stop          # Stop all services
make install       # Build release and install to ~/hero/bin
make build         # Standalone binary with embedded services
make check         # cargo check + clippy
make test          # Full test pipeline (build, start, test, stop)

Services

User Profile

Service	Socket / Port	Purpose
hero_redis	hero_redis.sock + port 3378	In-memory data store
hero_indexer	hero_indexer.sock	Full-text search
hero_indexer_ui	hero_indexer_ui.sock	Indexer admin panel
hero_embedder	hero_embedder.sock	Text embedding service
hero_embedder_ui	hero_embedder_ui.sock	Embedder admin panel
hero_osis	hero_osis.sock	Object storage API
hero_fossil	hero_fossil.sock	Code repositories
hero_auth	hero_auth.sock	OAuth2 authentication
hero_books	port 8883	Book management
hero_os	hero_os.sock	Hero OS core
hero_proxy	port 8080	Reverse proxy / API gateway

Admin Profile

Service	Socket / Port	Purpose
forgejo	forgejo.sock + port 3393	Git forge
forgejo_mcp	port 3395	MCP interface for Forgejo
hero_compute_manager	hero_compute_manager.sock	Compute resource manager
hero_embedder	hero_embedder.sock	Text embedding
my_router_path	my_router_path.sock + port 2918	Path-based router

Beta Profile

Service	Socket / Port	Purpose
hero_aibroker	hero_aibroker.sock	AI model broker
hero_claude	port 3780	Claude AI interface
hero_runner	port 3391	Task runner
hero_shrimp	hero_shrimp.sock	Shrimp AI service
mycelium	port 3392	Network mesh protocol

Sockets

All Unix sockets are located in:

~/hero/var/sockets/

The server daemon listens on:

~/hero/var/sockets/hero_services_server.sock

The admin UI listens on TCP port 7070 by default:

http://localhost:7070/admin/

CLI Commands

hero_services health                    # Check server health
hero_services list                      # List all services
hero_services start|stop|restart <name> # Control a service
hero_services logs [name] [-n LINES]    # View logs
hero_services config [name]             # Show configuration
hero_services install <name>            # Install a service
hero_services install-all               # Install all services
hero_services build-status              # Show build progress

Runtime Directories

~/hero/
├── bin/                          # Service binaries
├── src/                          # Source code (for build method)
├── var/
│   ├── sockets/                  # Unix domain sockets
│   │   ├── hero_services_server.sock
│   │   ├── hero_redis.sock
│   │   ├── hero_osis.sock
│   │   └── ...
│   └── hero_zero/
│       └── installed/            # Install tracking
└── cfg/zinit/                    # Generated zinit configs

Docker

make docker-build    # Build image with all services
make docker-push     # Build and push to forge.ourworld.tf
make docker-run      # Run locally with port mappings
make docker-login    # Authenticate to registry

Requirements

• Rust toolchain (1.92+)
• Git, Make
• Docker (for container builds)

License

Apache-2.0