horus/docs/getting-started.md

Getting Started with Horus

Quick start guide to running your first Horus job.

Prerequisites

• Redis server running
• Rust toolchain installed
• Horus repository cloned

Installation

Build from Source

# Clone repository
git clone https://git.ourworld.tf/herocode/horus
cd horus

# Build all components
cargo build --release

# Binaries will be in target/release/

Quick Start

1. Start Redis

# Using Docker
docker run -d -p 6379:6379 redis:latest

# Or install locally
redis-server

2. Start a Runner

# Start Hero runner
./target/release/herorunner my-runner

# Or SAL runner
./target/release/runner_sal my-sal-runner

# Or Osiris runner
./target/release/runner_osiris my-osiris-runner

3. Start the Supervisor

./target/release/supervisor --port 8080

4. Submit a Job

Using the Supervisor client:

use hero_supervisor_client::SupervisorClient;
use hero_job::Job;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SupervisorClient::new("http://localhost:8080")?;
    
    let job = Job::new(
        "my-runner",
        "print('Hello from Horus!')".to_string(),
    );
    
    let result = client.create_job(job).await?;
    println!("Job ID: {}", result.id);
    
    Ok(())
}

Example Workflows

Simple Heroscript Execution

# Job payload
print("Hello World")
!!git.list

SAL System Operation

// List files in directory
let files = os.list_dir("/tmp");
for file in files {
    print(file);
}

Osiris Data Storage

// Store user data
let users = osiris.model("users");
let user = users.create(#{
    name: "Alice",
    email: "alice@example.com"
});
print(`Created user: ${user.id}`);

Architecture Overview

┌──────────────┐
│ Coordinator  │  (Optional: For workflows)
└──────┬───────┘
       │
┌──────▼───────┐
│  Supervisor  │  (Job dispatcher)
└──────┬───────┘
       │
       │ Redis
       │
┌──────▼───────┐
│   Runners    │  (Job executors)
│  - Hero      │
│  - SAL       │
│  - Osiris    │
└──────────────┘

Next Steps

• Architecture Details
• Runner Documentation
• Supervisor API
• Coordinator Workflows
• Authentication

Common Issues

Runner Not Receiving Jobs

1. Check Redis connection
2. Verify runner ID matches job target
3. Check supervisor logs

Job Signature Verification Failed

1. Ensure job is properly signed
2. Verify public key is registered
3. Check signature format

Timeout Errors

1. Increase job timeout value
2. Check runner resource availability
3. Optimize job payload

Development

Running Tests

# All tests
cargo test

# Specific component
cargo test -p hero-supervisor
cargo test -p runner-hero

Debug Mode

# Enable debug logging
RUST_LOG=debug ./target/release/supervisor --port 8080

Support

• Documentation: docs.ourworld.tf/horus
• Repository: git.ourworld.tf/herocode/horus
• Issues: Report on the repository