horus/bin/horus/README.md

Horus - Hero System Mono Binary

A unified binary that runs all Hero system components: coordinator, supervisor, osiris server, and runners.

Installation

Build the binary:

cargo build -p horus-mono --release

The binary will be available at target/release/horus.

Usage

Run Individual Services

Coordinator

Manages job execution across runners:

horus coordinator \
  --mycelium-ip 127.0.0.1 \
  --mycelium-port 8990 \
  --redis-addr 127.0.0.1:6379 \
  --api-http-ip 127.0.0.1 \
  --api-http-port 9652 \
  --api-ws-ip 127.0.0.1 \
  --api-ws-port 9653

Supervisor

Manages actors and dispatches jobs:

horus supervisor \
  --redis-url redis://127.0.0.1:6379 \
  --admin-secret your-admin-secret \
  --port 3030 \
  --bind-address 127.0.0.1 \
  --runners osiris,sal,hero

Osiris Server

REST API server for Osiris data structures:

horus osiris \
  --bind-address 0.0.0.0 \
  --port 8081

Run All Services Together

Start all services with a single command:

horus all \
  --redis-url redis://127.0.0.1:6379 \
  --admin-secret your-admin-secret

Kill existing processes on ports before starting:

horus all \
  --redis-url redis://127.0.0.1:6379 \
  --admin-secret your-admin-secret \
  --kill-ports

This will start:

• Supervisor on http://127.0.0.1:3030
• Coordinator HTTP on http://127.0.0.1:9652
• Coordinator WebSocket on ws://127.0.0.1:9653
• Osiris Server on http://0.0.0.0:8081

The --kill-ports flag will automatically kill any processes using ports 3030, 8081, 9652, and 9653 before starting the services.

Environment Variables

You can also configure services using environment variables:

Coordinator

• MYCELIUM_IP - Mycelium IP address (default: 127.0.0.1)
• MYCELIUM_PORT - Mycelium port (default: 8990)
• REDIS_ADDR - Redis address (default: 127.0.0.1:6379)
• API_HTTP_IP - HTTP API bind IP (default: 127.0.0.1)
• API_HTTP_PORT - HTTP API port (default: 9652)
• API_WS_IP - WebSocket API bind IP (default: 127.0.0.1)
• API_WS_PORT - WebSocket API port (default: 9653)

Logging

Set the RUST_LOG environment variable to control logging:

RUST_LOG=info horus all --admin-secret your-secret

Available levels: error, warn, info, debug, trace

Prerequisites

• Redis server running on localhost:6379 (or specify custom address)
• For coordinator: Mycelium service running (if using Mycelium transport)

Architecture

The horus binary consolidates the following components:

1. Coordinator - Routes jobs between contexts and manages job execution
2. Supervisor - Manages runner registration and job dispatching
3. Osiris Server - Provides REST API for Osiris data structures
4. Runners (not included in mono binary, run separately):
   • OSIRIS runner - Script execution with Osiris support
   • SAL runner - Script execution with SAL support
   • Hero runner - Command execution

Examples

Development Setup

# Start Redis
redis-server

# Run all services (kills any existing processes on required ports)
RUST_LOG=info horus all --admin-secret dev-secret --kill-ports

Production Setup

# Build release binary
cargo build -p horus-mono --release

# Run with production settings
RUST_LOG=warn ./target/release/horus all \
  --redis-url redis://prod-redis:6379 \
  --admin-secret $ADMIN_SECRET

Help

For detailed help on any command:

horus --help
horus coordinator --help
horus supervisor --help
horus osiris --help
horus all --help