Epitrop
Epitrop is the agent runtime and task-graph engine for the Tekmora ecosystem. It reads its organisation, routines and budgets from files in Git and rebuilds state from an append-only, Ed25519-signed event log, without a database setup wizard.
Status: early. Today the repository ships the Go control plane (cmd/epitropctl, cmd/epitrop-server), the model catalog (catalog/, internal/sources/, moved from cordanaLLM/praetor with its history), the signed event log, the acyclic task graph, the sandboxed job supervisor, the agent slot runner and the MCP server. The runtime is planned across milestones 0.1 to 0.6; see the roadmap.
Why Epitrop
- Git-native configuration, no relational database: process configuration is validated against
docs/config.schema.jsonbefore decoding, and organisation, routines and budgets live in files in Git (Description). - Event-sourced state (RT-04): every task-graph edit, work-unit transition, job lifecycle event and outbound side-effect claim is recorded in a JCS-canonicalised (RFC 8785), Ed25519-signed event log (
internal/eventlog) with segment rotation (ADR-0010), Git checkpoint commits ontorefs/epitrop/events(ADR-0011) and signed base compaction (ADR-0012). - Acyclic task graph and deterministic frontier:
internal/graphenforces Kahn acyclicity, bounded depth and staged rollback, andinternal/scoreorders ready work units deterministically from event-log records alone (Architecture). - Control-plane isolation and sandboxed supervision (RT-03): declared background jobs and headless agent slots (
internal/supervisor,internal/slot) start through a per-job shim in Linuxsystemd-runuser scopes andbubblewrapsandboxes (ADR-0005) withnone,egressor Unix-socketproxynetwork modes (ADR-0006), unchanged arguments (ADR-0007), declared input roots (ADR-0008) and read-only bound logins (ADR-0009). - Deterministic edges and at-most-once side effects (RT-01, RT-02):
internal/edgeschecks model calls for temperature 0 and JSON Schema validation,internal/effectsruns each(task_id, action_type)side effect at most once, andinternal/brokerprovides log-first fan-out with bounded subscriber queues and dead-letter classification (internal/jobfailure). - Router-alias model routing and measured budgets: every model call goes through a router alias over one dynamic accelerator pool, platform budgets (
internal/budget) read the Praetor efficiency ledger (internal/ledger), and the model catalog collects live usage windows and burn rates without silent fallbacks (Catalog data sync).
Documentation map
| Section | Page | What it covers |
|---|---|---|
| Architecture | Description | Core idea, six design pillars and EUPL-1.2 licensing |
| Architecture | Control Plane & Invariants | Go control plane, event log, agent slots and runtime invariants RT-01 to RT-04 |
| Architecture | Repository Layout | Current packages, binaries and planned Rust and Svelte 5 directories |
| Architecture | Sources | Verified reference links behind the Epitrop design |
| Guides & Operations | Agent Onboarding | Package map, HISS limits, RT invariants and verification workflow |
| Guides & Operations | Catalog Data Sync | Installing epitropctl, running sync, show, headroom and claude-limits |
| Guides & Operations | MCP Server | Serving the run record, health probes and /events SSE stream with epitrop-server |
| Guides & Operations | Telemetry | OpenTelemetry spans and metrics exported over OTLP |
| Guides & Operations | Cutover 1 | Moving fleet watchers and background jobs to the Epitrop supervisor |
| Guides & Operations | Releasing | Tagging, keyless cosign signing, SLSA provenance verification and upgrade fixtures |
| Guides & Operations | Roadmap | Milestones 0.1 to 0.6, critical path and Praetor interfaces |
| Decisions (ADRs) | ADR Index | Accepted architectural decision records (ADR-0000 and ADR-0004 to ADR-0012) |