03Open source
Hekma is the open-source control plane for agent workloads: one way to run, see and steer AI agents, from a laptop to a fleet. Today it is a Rust CLI and engine that supervises agents, meters every run’s real token use and enforces budgets the moment they’re crossed. The rest is being built in the open, so you can read how I work before we talk.
An agent here is a third-party program that calls a model on your behalf, such as a personal agent or a coding agent. Hekma launches, supervises, meters and budgets it as a process. It is not a framework for writing agents.
Start, stop, pause and resume any registered agent through one state machine, with crash detection, a restart policy, captured logs and durable state in a single SQLite database.
Real per-run and cumulative token totals in an append-only usage ledger. Usage is either reported by the agent or observed by the engine through a loopback proxy on the agent’s model traffic.
Token ceilings per run and in total, and cost caps once you set a rate. A breach pauses, stops or warns, checked in the same commit path as the usage that crossed it. Costs are stored as integers, never floats, and always labelled as estimates.
In development: every agent becomes a Run you can list and label, and Policies set limits for many Runs at once, warning by default rather than stopping work. Planned: a key per Run and control on the model wire. Each piece is tagged by stage on hekma.ktesio.dev until it ships.
Fig. 1 One fleet in Hekma: run, see and steer
policy fleet-prod · env=prod · 200M per run · warn
| Run | Kind | State | Control | Tokens |
|---|---|---|---|---|
| pay-triage | Hermes · ACP | running | start, pause, stop | 56% |
| docs-writer | OpenCode · ACP | paused | start, pause, stop | 38% |
| research-a | CrewAI flow | running anomaly | hold | 104% |
| claims-b | LangGraph | running | hold | 70% |
| summarise | model call | running | hold | 22% |
telemetry OTLP metrics · events · logs your collector unreleased
ships in 0.11.0 being built
# install from crates.io
$ cargo install hekma
# register an agent from its adapter.toml
$ hekma agent register my-agent --manifest ./my-agent
# cap its token usage and pause it on a breach
$ hekma agent config set my-agent budget.tokens.cumulative 300000000
$ hekma agent config set my-agent budget.breach_action pause
# run it under supervision
$ hekma agent start my-agenthekma, hkmIt also says what it can’t see. Model traffic that doesn’t pass through its proxy isn’t metered, cost figures are estimates from a flat rate, and requests already in flight when a budget trips still reach the provider. The design essay covers each gap.
Why Hekma meters an agent’s model traffic at a boundary the agent cannot bypass, how the loopback proxy, the usage ledger and budget enforcement fit together, and what the meter still cannot see.
Cost governance cannot depend on the agent’s cooperation.