fix: rename overview.md files to avoid conflicts and add collection name

This commit is contained in:
Timur Gordon
2025-11-14 11:01:43 +01:00
parent f67296cd25
commit 2c24b120de
20 changed files with 85 additions and 91 deletions

96
docs/runner/runners.md Normal file
View File

@@ -0,0 +1,96 @@
# 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