horus/docs/runner/runners.md

Runners Overview

Runners are the execution layer in the Horus architecture. They receive jobs from the Supervisor via Redis queues and execute the actual workload.

Architecture

Supervisor → Redis Queue → Runner → Execute Job → Return Result

Available Runners

Horus provides three specialized runners:

1. Hero Runner

Executes heroscripts using the Hero CLI ecosystem.

Use Cases:

• Running Hero automation tasks
• Executing heroscripts from job payloads
• Integration with Hero CLI tools

Binary: herorunner

→ Hero Runner Documentation

2. SAL Runner

System Abstraction Layer runner for system-level operations.

Use Cases:

• OS operations (file, process, network)
• Infrastructure management (Kubernetes, VMs)
• Cloud provider operations (Hetzner)
• Database operations (Redis, Postgres)

Binary: runner_sal

→ SAL Runner Documentation

3. Osiris Runner

Database-backed runner for data storage and retrieval using Rhai scripts.

Use Cases:

• Structured data storage
• Model-based data operations
• Rhai script execution with database access

Binary: runner_osiris

→ Osiris Runner Documentation

Common Features

All runners implement the Runner trait and provide:

• Job Execution: Process jobs from Redis queues
• Signature Verification: Verify job signatures before execution
• Timeout Support: Respect job timeout settings
• Environment Variables: Pass environment variables to jobs
• Error Handling: Comprehensive error reporting
• Logging: Structured logging for debugging

Runner Protocol

Runners communicate with the Supervisor using a Redis-based protocol:

1. Job Queue: Supervisor pushes jobs to runner:{runner_id}:jobs
2. Job Processing: Runner pops job, validates signature, executes
3. Result Storage: Runner stores result in job:{job_id}:result
4. Status Updates: Runner updates job status throughout execution

Starting a Runner

# Hero Runner
herorunner <runner_id> [--redis-url <url>]

# SAL Runner
runner_sal <runner_id> [--redis-url <url>]

# Osiris Runner
runner_osiris <runner_id> [--redis-url <url>]

Configuration

All runners accept:

• runner_id: Unique identifier for the runner (required)
• --redis-url: Redis connection URL (default: redis://localhost:6379)

Security

• Jobs must be cryptographically signed
• Runners verify signatures before execution
• Untrusted jobs are rejected
• Environment variables should not contain sensitive data in production