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      examples

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_examples	examples	Example programs demonstrating SDK usage

Quick Start

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

Make Targets

make run           # Build release, install, and run via zinit
make rundev        # Build debug, install, and run via zinit (debug logging)
make stop          # Stop all services
make restart       # Restart all services
make status        # Show service status (zinit list)
make logs          # Show server logs
make logs-ui       # Show UI logs
make install       # Build release and install to ~/hero/bin
make installdev    # Build debug and install to ~/hero/bin
make build         # Standalone binary with embedded services
make check         # cargo check + clippy
make test          # Run unit tests
make test-all      # Full test pipeline (unit + integration)

Sockets

All Unix sockets are located in:

~/hero/var/sockets/

Service	Socket
Server (JSON-RPC)	~/hero/var/sockets/hero_services_server.sock
Admin UI (HTTP)	~/hero/var/sockets/hero_services_ui.sock

No services bind TCP ports directly.

Accessing the Admin UI

Option 1 — hero_inspector (recommended for development):

hero_inspector can open any socket-based UI in your browser by spawning a local TCP→socket reverse proxy on a free port:

# Install and run hero_inspector with its own HTTP UI
cd ../hero_inspector && make install
hero_inspector_ui --http --port 8802 --open

Then use the inspector UI at http://localhost:8802 to discover all running services. Click Open on any web UI service (e.g. hero_services_ui) and the inspector will proxy it to a localhost port automatically.

Programmatically via JSON-RPC:

curl --unix-socket ~/hero/var/sockets/hero_inspector_ui.sock \
  -X POST http://localhost/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"inspector.open_website","params":{"service_id":"hero_services_ui"}}'

Returns { "port": 9100, "url": "http://127.0.0.1:9100" } — open that URL.

Option 2 — hero_proxy (production):

hero_proxy (port 8805) auto-discovers all sockets and routes by path:

http://localhost:8805/hero_services/

Option 3 — curl directly (quick debugging):

curl --unix-socket ~/hero/var/sockets/hero_services_ui.sock http://localhost/

Service Configuration Format

Each service is defined in a single TOML file under services/{profile}/. A service has a [server] component (required) and an optional [ui] component. Each component specifies how to install it — either by downloading a pre-built binary or building from source.

Minimal example (build from source)

[service]
name = "hero_redis"
description = "Redis — in-memory data store"

[server]
exec = "__HERO_BIN__/hero_redis_openrpc"
build = "ssh://git@forge.ourworld.tf/lhumina_code/hero_redis.git"
install = { method = "build", branch = "development" }

[env]
RUST_LOG = "info"

[profile]
description = "Redis — in-memory data store"
actions = ["install", "run", "health"]

Full example (server + UI, download + build, shared build options)

[service]
name = "hero_os"
description = "Hero OS — web UI and backend"
depends_on = ["hero_osis_server"]

# Shared build options (features, source_deps) — applies to all components
[build]
features = ["web"]
base_features = ["core"]
required_features = ["island-archipelagos", "island-settings"]
available_features = ["island-ai", "island-chat", "island-calendar"]

[server]
exec = "__HERO_BIN__/hero_os_openrpc"
download = "https://releases.ourworld.tf/hero_os/{version}/hero_os-{os}-{arch}"
build = "ssh://git@forge.ourworld.tf/lhumina_code/hero_os.git"
install = { method = "build", branch = "development" }

[ui]
exec = "__HERO_BIN__/hero_os_http"
ports = [8804]
kill_others = true

[env]
RUST_LOG = "info"

[profile]
description = "Hero OS — web UI and backend"
actions = ["install", "run", "health"]

Component fields

Each component ([server] or [ui]) supports:

Field	Type	Description
exec	string	Command to run (required)
download	string	Release URL template with {version}, {os}, {arch} placeholders
build	string	Git repo URL for building from source
install	inline table	Install instructions (see below)
ports	array	TCP ports used
kill_others	bool	Kill processes on declared ports before starting
env	table	Component-specific environment variables
oneshot	bool	Run once and exit (for setup scripts)

Install instructions

# Download a specific version
install = { method = "download", version = "0.3.14" }

# Build from a branch
install = { method = "build", branch = "development" }

# Build from a specific commit
install = { method = "build", commit = "abc123" }

UI with its own build

When the UI comes from a different repo than the server, give it its own build and install:

[server]
exec = "__HERO_BIN__/hero_indexer"
build = "ssh://git@forge.ourworld.tf/lhumina_code/hero_index_server.git"
install = { method = "build", branch = "development" }

[ui]
exec = "__HERO_BIN__/hero_indexer_ui"
build = "ssh://git@forge.ourworld.tf/lhumina_code/hero_indexer_ui.git"
install = { method = "build", branch = "development" }

When the UI shares the server's build (same repo produces both binaries), omit build and install from [ui].

Placeholders

Placeholder	Resolves to
__HERO_BIN__	~/hero/bin/
__HERO_VAR__	~/hero/var/
__HERO_ROOT__	~/hero/
__HERO_SRC__	~/hero/src/ (or $CODEROOT)

Naming convention

At load time, the unified TOML expands into zinit services:

• [server] → {name}_server (e.g. hero_redis_server)
• [ui] → {name}_ui (e.g. hero_redis_ui)

Cross-service dependencies use these expanded names:

depends_on = ["hero_redis_server", "hero_indexer_server"]

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

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_services_ui.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, zinit
• Docker (for container builds)

Add ~/hero/bin to your $PATH:

export PATH="$HOME/hero/bin:$PATH"

License

Apache-2.0