horus/docs/supervisor/supervisor.md

Supervisor Overview

The Supervisor is the job dispatcher layer in Horus. It receives jobs, verifies signatures, and routes them to appropriate runners.

Architecture

Client → Supervisor → Redis Queue → Runner

Responsibilities

1. Job Admission

• Receive jobs via OpenRPC interface
• Validate job structure and required fields
• Verify cryptographic signatures

2. Authentication & Authorization

• Verify job signatures using public keys
• Ensure jobs are from authorized sources
• Reject unsigned or invalid jobs

3. Job Routing

• Route jobs to appropriate runner queues
• Maintain runner registry
• Load balance across available runners

4. Job Management

• Track job status and lifecycle
• Provide job query and listing APIs
• Store job results and logs

5. Runner Management

• Register and track available runners
• Monitor runner health and availability
• Handle runner disconnections

OpenRPC Interface

The Supervisor exposes an OpenRPC API for job management:

Job Operations

• create_job: Submit a new job
• get_job: Retrieve job details
• list_jobs: List all jobs
• delete_job: Remove a job
• get_job_logs: Retrieve job execution logs

Runner Operations

• register_runner: Register a new runner
• list_runners: List available runners
• get_runner_status: Check runner health

Job Lifecycle

1. Submission: Client submits job via OpenRPC
2. Validation: Supervisor validates structure and signature
3. Queueing: Job pushed to runner's Redis queue
4. Execution: Runner processes job
5. Completion: Result stored in Redis
6. Retrieval: Client retrieves result via OpenRPC

Transport Options

The Supervisor supports multiple transport layers:

• HTTP: Standard HTTP/HTTPS transport
• Mycelium: Peer-to-peer encrypted transport

Configuration

# Start supervisor
supervisor --port 8080 --redis-url redis://localhost:6379

# With Mycelium
supervisor --port 8080 --mycelium --redis-url redis://localhost:6379

Security

• All jobs must be cryptographically signed
• Signatures verified before job admission
• Public key infrastructure for identity
• Optional TLS for HTTP transport
• End-to-end encryption via Mycelium

→ Authentication Documentation