Agent runtime and task-graph engine for the Tekmora ecosystem
File-based, Git-native control plane, sandboxed job runner and model catalog, governed by Praetor
Epitrop 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 holds the model
catalog (catalog/, cmd/epitropctl, internal/sources/), moved from
cordanaLLM/praetor with its history, together with the Go control plane
(cmd/epitropctl, cmd/epitrop-server), the signed event log, the acyclic task
graph, the sandboxed job supervisor, the agent slot runner and the MCP server.
The runtime is planned in milestones 0.1 to 0.6; see the
roadmap.
Full documentation · Documentation source
Epitrop keeps runtime state in Git and an append-only event log while isolating
task execution from the control plane (docs/epitrop-description-v2.md,
docs/architecture-v2.md):
- 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 (ADR-001; Paperclip is not required). - 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, Git checkpoint commits ontorefs/epitrop/eventsand signed base compaction. - 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. - 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 (MemoryMax,MemoryHigh,CPUWeight,TasksMax) andbubblewrapsandboxes withnone,egressor Unix-socketproxynetwork modes (internal/egressproxy), lock-backed liveness and read-only bound logins. - 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. - Planned vector kernel and operator UI: a Rust vector kernel (SIMD cosine
and Euclidean skill matching over
f32,f16andi8vectors) and a Svelte 5 runes operator UI complete the planned stack.
The runtime is called Epitrop (eh-PEE-trop), from Greek epitropos, the
appointed trustee. Tekmora, the family the name belongs to, comes from Greek
tekmor: a set goal, and the sign that shows the way to it; said TEK-mo-ra.
The repository was first named tribunus, in another organisation; its old
address redirects.
Build and test the repository from a checkout:
go build -v ./...
go vet ./...
go test -race ./...Install epitropctl from the checkout (or pin a release tag with
go install github.com/tekmora/epitrop/cmd/epitropctl@<tag>; see
Catalog data sync), or run it without installing:
go install ./cmd/epitropctl
go run ./cmd/epitropctl versiongo install places the binary in $(go env GOBIN) or, when unset,
$(go env GOPATH)/bin, which must be on PATH for the epitropctl commands
below.
Run the first CLI command (epitropctl version or epitropctl sync) and the
operator subcommands:
epitropctl sync [--sources=a,b] [--out=file]
epitropctl show [--in=file]
epitropctl headroom --max-age=duration [--in=file]
epitropctl claude-limits [--claude-projects-dir=dir]
epitropctl schema
epitropctl version
epitropctl jobs start|status|stop --config=file [name]
epitropctl jobs history --config=file [--since=RFC3339] [name]
epitropctl jobs supervise --config=file [--poll-interval-seconds=1]epitropctl sync writes a versioned catalog snapshot with schema_version: 1.
The contract is described by catalog/snapshot.schema.json, and
epitropctl schema prints the embedded copy for downstream pin checks.
epitropctl version prints the release version, or dev for a source build.
epitropctl jobs supervise runs until SIGTERM or an interrupt, which end it
with exit 0, so a host service unit can hold it. After 365 days it returns a
deadline error and exits 1; a host unit configured to restart on that exit (for
example, Restart=on-failure) keeps supervision running. When at least one job
is down and none is alive, it writes at most one recoverable no job alive finding line
per episode to stderr and always attempts a terminal line if the finding becomes
terminal. Running jobs and armed cron/event jobs are alive; stopped cron and
event jobs remain armed and alive. A once job with no record or whose last run
exited 0 without reason deadline is excluded, as are stopped always and once
jobs; any other once end, including a deadline end with exit code 0 or a
lock-free running record confirmed lost, counts as down and cannot recover. If
a windowed restart budget can recover, the line includes
restart due <RFC3339Nano UTC> and ends supervise keeps running; otherwise it
ends supervise exits 3 and the command exits 3. A job becoming alive ends the
episode. jobs stop also keeps an on-failure always job stopped. Put
RestartPreventExitStatus=3 in the unit to make a terminal finding fail it at
once instead of restarting.
Releases, their signed artefacts and how to verify them are described in
Releasing.
epitropctl exports OpenTelemetry traces and metrics over OTLP once
OTEL_EXPORTER_OTLP_ENDPOINT or a signal-specific endpoint is set. With no
endpoint set, nothing is exported. Telemetry lists the
spans and metrics. epitrop-server --config=file serves the run record over the
Model Context Protocol; see MCP server.
%%{init: {'theme': 'base', 'themeVariables': {'fontFamily': 'ui-sans-serif, Segoe UI, Helvetica, Arial, sans-serif', 'fontSize': '15px', 'primaryColor': '#111a35', 'primaryTextColor': '#e2e8f0', 'primaryBorderColor': '#3b82f6', 'lineColor': '#3b82f6', 'edgeLabelBackground': '#111a35', 'tertiaryColor': '#0b1020'}}}%%
flowchart TD
cfg["Git config & schema<br/>docs/config.schema.json"]:::input
src["Catalog sources<br/>gateway · local · public"]:::input
snap["Catalog snapshot<br/>schema_version: 1"]:::step
sup["Job supervisor<br/>schedules · triggers · locks"]:::step
shim["Per-job shim & sandbox<br/>systemd scope · bwrap · proxy"]:::step
jobs["Supervised jobs & slots<br/>watch · harnesses · scripts"]:::step
log[("Signed event log<br/>JCS · Ed25519 · checkpoints")]:::step
tg["Task graph & units<br/>DAG · scoring · effects"]:::step
mcp["MCP & HTTP server<br/>stdio · loopback · /events"]:::step
src --> snap
cfg --> sup --> shim --> jobs --> log
cfg --> tg
log --> tg --> mcp
log --> mcp
classDef input fill:#0b1020,stroke:#06b6d4,stroke-width:2px,color:#e2e8f0
classDef step fill:#111a35,stroke:#3b82f6,stroke-width:2px,color:#e2e8f0
classDef decide fill:#111a35,stroke:#8b5cf6,stroke-width:2px,color:#e2e8f0
| Task | Documentation |
|---|---|
| Start working in the repository and inspect package boundaries | Agent onboarding |
| Read the project overview and six design pillars | Description |
| Understand the Go control plane, event log, agent slots and RT-01 to RT-04 | Architecture |
| Navigate existing packages, binaries and planned directories | Repository layout |
Install epitropctl, sync the model catalog and inspect source limits |
Catalog data sync |
Serve the run record, probes and /events stream over MCP and loopback HTTP |
MCP server |
| Export OpenTelemetry spans and metrics over OTLP | Telemetry |
| Run background jobs in parallel before switching over | Cutover 1 |
| Cut, sign and verify releases and check upgrade fixtures | Releasing |
| Track milestones 0.1 to 0.6 and Praetor interfaces | Roadmap |
| Browse the verified reference links behind the design | Sources |
| Review accepted architectural decision records | ADR index |
Start with CONTRIBUTING.md for the HISS rules, 3D testing requirements, Conventional Commits and local verification. Read Agent onboarding for the package map.
- Report a bug or track work
- Ask a question or join discussions
- Report a security vulnerability privately (GitHub private vulnerability reporting)
Sponsor the work on GitHub Sponsors or Ko-fi, any amount; no support or priority is sold.
- Roadmap and milestones 0.1 to 0.6
- Releases and signed downloads
- Changelog
- Release process and verification
EUPL-1.2, for code and documents alike. See LICENSE and
REUSE.toml. Third-party code that epitropctl includes, with
the notice each licence asks to carry, is listed in NOTICE.md.
The Go control plane builds on pinned
golusoris modules under EUPL-1.2
(ADR-0004), and the model catalog
moved from cordanaLLM/praetor with
its history.
This repository conforms to High-Integrity Systems Standards (HISS-21).
Praetor manages this repository's declared governance policy. This managed block records adoption state; it is not a verification certificate.
Verification: make verify-all runs the repository's configured
verification cascade.
HISS Audit: praetorctl audit enforces policy, generated-surface
integrity, and the debt ratchet.
Context Sync: praetorctl compile-context --verify verifies every
generated agent context against AGENTS.md.
Documentation: make docs-lint enforces locked Markdown style and the
private scratch-link policy.
Debt Baseline: .standards-baseline.json anchors the debt ratchet at
4 recorded infractions; audit forbids growth.