home/scripts

Hero System Scripts

This directory contains wrapper scripts for building and running the Hero system components.

Overview

The Hero system consists of three main components:

• Hero Coordinator: Manages job coordination and routing
• Hero Supervisor: Manages runner processes and job execution
• Osiris Runner: Executes jobs using the Osiris protocol

Architecture

The scripts in this directory are wrappers that delegate to individual component scripts:

• home/scripts/build.sh → calls build.sh in each component repo
• home/scripts/run.sh → calls run.sh in each component repo
• Each component's run.sh → calls its own build.sh before running

This ensures each component is self-contained and can be built/run independently.

Scripts

build.sh

Wrapper that builds all Hero system components by calling their individual build scripts.

Usage:

./build.sh

This calls:

• herocoordinator/scripts/build.sh
• supervisor/scripts/build.sh
• runner_rust/scripts/build.sh

run.sh

Manages Hero system services.

Usage:

./run.sh [command]

Commands:

• start - Start all services (default) - each service builds itself first
• stop - Stop all services
• restart - Restart all services
• status - Show status of all services
• logs - Tail all service logs

Examples:

./run.sh start    # Start all services (builds automatically)
./run.sh status   # Check status
./run.sh logs     # View logs
./run.sh stop     # Stop all services
./run.sh restart  # Restart all services

Note: Each component's run.sh automatically calls its build.sh before starting, so you don't need to build manually.

Components

Coordinator

• Binary: herocoordinator/target/release/herocoordinator
• Port: 8081 (configurable via COORDINATOR_PORT)
• Purpose: Coordinates job execution across the system

Supervisor

• Binary: supervisor/target/release/supervisor
• Port: 3030 (configurable via SUPERVISOR_PORT)
• Purpose: Manages runners and job dispatch via OpenRPC

Osiris Runner

• Binary: runner_rust/target/release/runner_osiris
• Purpose: Executes Osiris-specific jobs

Configuration

Set environment variables before running:

# Redis connection
export REDIS_URL="redis://127.0.0.1:6379"

# Service ports
export COORDINATOR_PORT=8081
export SUPERVISOR_PORT=3030

# Logging
export LOG_LEVEL=info  # Options: trace, debug, info, warn, error

Logs and PIDs

• Logs: /Users/timurgordon/code/git.ourworld.tf/herocode/home/logs/

  • coordinator.log
  • supervisor.log
  • osiris_runner.log

• PIDs: /Users/timurgordon/code/git.ourworld.tf/herocode/home/pids/

  • coordinator.pid
  • supervisor.pid
  • osiris_runner.pid

Prerequisites

1. Redis must be running:

   redis-server
   

2. Rust toolchain must be installed:

   rustc --version
   cargo --version
   

Troubleshooting

Services won't start

1. Check if binaries are built:

   ls -la ../herocoordinator/target/release/herocoordinator
   ls -la ../supervisor/target/release/supervisor
   ls -la ../runner_rust/target/release/runner_osiris
   

2. If missing, build them:

   ./build.sh
   

Check logs

# View all logs
./run.sh logs

# Or view individual logs
tail -f ../home/logs/coordinator.log
tail -f ../home/logs/supervisor.log
tail -f ../home/logs/osiris_runner.log

Redis not running

# Start Redis
redis-server

# Or in background
redis-server --daemonize yes

Port already in use

Change the port via environment variables:

COORDINATOR_PORT=8082 SUPERVISOR_PORT=3031 ./run.sh start

Development Workflow

# 1. Make code changes
# ... edit code ...

# 2. Rebuild affected component
./build.sh coordinator  # or supervisor, or runner

# 3. Restart services
./run.sh restart

# 4. Check logs
./run.sh logs