# 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](./hero.md)

### 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](./sal.md)

### 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](./osiris.md)

## 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

```bash
# 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