supervisor/QUICK_START.md

Quick Start Guide

Complete guide to running the Hero Supervisor with OSIS runners and examples.

Prerequisites

1. Redis - Must be running
2. Rust - Version 1.88+ (run rustup update)

1. Start Redis

redis-server

2. Start Supervisor

cd /Users/timurgordon/code/git.ourworld.tf/herocode/supervisor
cargo run --bin supervisor

You should see:

╔════════════════════════════════════════════════════════════╗
║  Hero Supervisor Started                                   ║
╚════════════════════════════════════════════════════════════╝
  📡 OpenRPC Server: http://127.0.0.1:3030
  🔗 Redis: redis://localhost:6379
  🌐 Mycelium: Not compiled (use --features mycelium)
╚════════════════════════════════════════════════════════════╝

3. Start OSIS Runner

cd /Users/timurgordon/code/git.ourworld.tf/herocode/runner_rust
cargo run --bin runner_osis -- test_runner \
    --redis-url redis://localhost:6379 \
    --db-path /tmp/test_runner.db

You should see:

Starting OSIS Sync Runner with ID: test_runner
Database path: /tmp/test_runner.db
Redis URL: redis://localhost:6379
OSIS Sync Runner 'test_runner' started successfully

4. Run Example

cd /Users/timurgordon/code/git.ourworld.tf/herocode/supervisor
RUST_LOG=info cargo run --example simple_e2e

Terminal Layout

┌─────────────────────┬─────────────────────┐
│  Terminal 1         │  Terminal 2         │
│  Redis              │  Supervisor         │
│  redis-server       │  cargo run --bin    │
│                     │  supervisor         │
├─────────────────────┼─────────────────────┤
│  Terminal 3         │  Terminal 4         │
│  OSIS Runner        │  Example            │
│  cargo run --bin    │  cargo run          │
│  runner_osis        │  --example          │
│                     │  simple_e2e         │
└─────────────────────┴─────────────────────┘

What Each Component Does

Redis

• Job queue storage
• Job result storage
• Runner coordination

Supervisor

• OpenRPC HTTP server (port 3030)
• Job dispatch to runners
• Runner registration
• Job execution coordination

OSIS Runner

• Listens for jobs on Redis queue
• Executes Rhai scripts
• Stores results back to Redis
• Uses HeroDB for data persistence

Example

• Creates jobs with Rhai scripts
• Sends jobs to supervisor via OpenRPC
• Receives results
• Demonstrates both blocking and non-blocking modes

Architecture

┌─────────────┐
│   Example   │  (simple_e2e.rs)
└──────┬──────┘
       │ HTTP/JSON-RPC
       ▼
┌─────────────┐
│ Supervisor  │  (port 3030)
└──────┬──────┘
       │ Redis Queue
       ▼
┌─────────────┐
│ OSIS Runner │  (test_runner)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   HeroDB    │  (Redis + local DB)
└─────────────┘

Troubleshooting

"Connection refused" on port 3030

• Make sure supervisor is running
• Check if another process is using port 3030

"Connection refused" on port 6379

• Make sure Redis is running
• Check: redis-cli ping (should return "PONG")

Runner not receiving jobs

• Check runner is registered: Look for "Runner registered successfully" in example output
• Check Redis connection: Both supervisor and runner must use same Redis URL
• Check queue name matches: Should be hero:q:work:type:osis:group:default:inst:test_runner

"Job execution timeout"

• Increase timeout in job builder: .timeout(120)
• Check if runner is actually processing jobs (look for logs)

Example Output

Successful Run

╔════════════════════════════════════════╗
║  Simple End-to-End Demo               ║
╚════════════════════════════════════════╝

📋 Step 1: Registering Runner
─────────────────────────────────────────
✅ Runner registered successfully

📋 Step 2: Running a Simple Job (Blocking)
─────────────────────────────────────────
✅ Job completed!
   Result: {"message":"Hello from the runner!","number":42}

📋 Step 3: Running a Calculation Job
─────────────────────────────────────────
✅ Calculation completed!
   Result: {"sum":55,"product":3628800,"count":10}

📋 Step 4: Starting a Non-Blocking Job
─────────────────────────────────────────
✅ Job started!
   Job ID: abc-123 (running in background)

🎉 Demo completed successfully!

Next Steps

1. Try different Rhai scripts - Modify the payload in examples
2. Add more runners - Start multiple runners with different IDs
3. Explore the API - Use the OpenRPC client library
4. Build your own client - See clients/openrpc/ for examples

Useful Commands

# Check Redis
redis-cli ping

# List Redis keys
redis-cli keys "hero:*"

# Monitor Redis commands
redis-cli monitor

# Check supervisor is running
curl http://localhost:3030

# View runner logs
# (check terminal where runner is running)

Clean Up

# Stop all processes (Ctrl+C in each terminal)

# Clean up test database
rm /tmp/test_runner.db

# (Optional) Flush Redis
redis-cli FLUSHALL

---

Status: ✅ Ready to Use Last Updated: 2025-10-24