hekma
Menu

run · see · steer

The control plane
for agent workloads.

One way to run, see and steer every agent you depend on: coding agents like OpenCode, personal agents like Hermes Agent, CrewAI and LangGraph flows, or a raw model call. From a laptop to a fleet, and built to signal loudly rather than stop work, so that Hekma is never the reason prod stops. Today it supervises, meters and budgets the agents you run. Runs, Policies and wire control are being built in the open.

curl -fsSL https://cli.ktesio.dev/hekma/install.sh | sh

macOS · Linux · Windows · Apache-2.0 Windows & other install methods

your fleetships in 0.11.0being built

policy fleet-prod · env=prod · 200M per run · warn

runkindstatecontroltokens
pay-triageHermes · ACPrunningstart, pause, stop
56%
docs-writerOpenCode · ACPpausedstart, pause, stop
38%
research-aCrewAI flowrunning anomalyhold
104%
claims-bLangGraphrunninghold
70%
summarisemodel callrunninghold
22%

telemetry OTLP metrics · events · logs your collector unreleased

An illustration with example values. Hermes and OpenCode run under Hekma today, with start, pause and stop. Policies, CrewAI and LangGraph Runs, and hold are being built; past its ceiling, research-a gets an Anomaly and keeps running.
v0.11.0latest release1 binaryrust, no runtime depsApache-2.0licence3 platformsmacos · linux · windows

the control plane · being built in the open

roadmap

in development

Every agent is a Run.

Every supervised agent, and each piece of work a Host opens inside one, becomes a Run with an id, labels and a Control Depth that says how much Hekma can do to it. hekma ps lists them exception-first, so healthy Runs are a count and the ones that need you are rows. Runs Hekma did not start follow, planned.

design sketch · may change

$ hekma ps --selector flow=claims
RUN           CONTROL     STATUS  ANOMALIES
run_01JD…X4   supervised  held    budget-breach
38 healthy Runs not shown

in development

Signal, don’t stop.

Policies set standing limits by label, and the most specific one wins. A breach becomes warn by default: an Anomaly in hekma ps, an event, a metric and a response header your framework can act on. Pausing, stopping or fencing a Run stays your explicit choice.

design sketch · may change

$ hekma policy create claims-prod \
    --selector env=prod,flow=claims \
    --cost-cap 25.00 --breach-action warn

planned

One key per Run.

Each Run gets a Run Key that sits where the agent expects its provider API key. The real key stays with Hekma and is swapped in at the proxy, so every call through it is attributed to its Run, and a supervised agent that calls the provider around Hekma is flagged.

design sketch · may change

OPENAI_API_KEY=hk_run_…   # what the agent holds
# the provider key never leaves Hekma

planned

Attach and steer on the wire.

Point a framework’s base URL at Hekma, announce a Run with one header, or send OpenTelemetry, and the flow shows up next to your supervised agents. Hold a Run’s next model call with its state intact, then release it, reroute it to a cheaper model, or reject it.

design sketch · may change

export OPENAI_BASE_URL=http://127.0.0.1:<proxy-port>/support
$ hekma hold --selector team=support
the fleet, under supervision
4 stand-in agents · hekma 0.11.0
logs --follow
$ hekma agent logs pay-triage --follow
2026-10-22T19:21:16Z [agent-out] session started (pid 88344)
2026-10-22T19:21:16Z [engine] engine: starting -> running
2026-10-22T19:21:16Z [agent-out] PAY-2281 refund stuck in pending: routed to billing
2026-10-22T19:21:16Z [agent-out] KTESIO_USAGE {"sequence": 0, "input_tokens": 31420, "output_tokens": 2610}
2026-10-22T19:21:17Z [agent-out] PAY-2282 duplicate charge: routed to disputes
2026-10-22T19:21:17Z [agent-out] KTESIO_USAGE {"sequence": 1, "input_tokens": 28870, "output_tokens": 3120}
2026-10-22T19:21:18Z [agent-out] PAY-2283 card declined at checkout: answered, closed
2026-10-22T19:21:18Z [agent-out] KTESIO_USAGE {"sequence": 2, "input_tokens": 33910, "output_tokens": 2480}
2026-10-22T19:21:19Z [agent-out] PAY-2284 invoice in wrong currency: routed to billing
2026-10-22T19:21:19Z [agent-out] KTESIO_USAGE {"sequence": 3, "input_tokens": 30150, "output_tokens": 2890}
2026-10-22T19:21:20Z [agent-out] PAY-2285 chargeback notice: needs a human
2026-10-22T19:21:20Z [agent-out] KTESIO_USAGE {"sequence": 4, "input_tokens": 29640, "output_tokens": 3310}
2026-10-22T19:21:21Z [agent-out] PAY-2286 payout delayed: answered, closed
2026-10-22T19:21:21Z [agent-out] KTESIO_USAGE {"sequence": 5, "input_tokens": 32780, "output_tokens": 2750}
2026-10-22T19:21:22Z [agent-out] PAY-2287 VAT missing on receipt: routed to billing
2026-10-22T19:21:22Z [agent-out] KTESIO_USAGE {"sequence": 6, "input_tokens": 27960, "output_tokens": 2940}
2026-10-22T19:21:23Z [agent-out] PAY-2288 3DS loop on mobile: routed to checkout
2026-10-22T19:21:23Z [agent-out] KTESIO_USAGE {"sequence": 7, "input_tokens": 34210, "output_tokens": 3080}
2026-10-22T19:21:24Z [agent-out] PAY-2289 refund to closed card: needs a human
2026-10-22T19:21:24Z [agent-out] KTESIO_USAGE {"sequence": 8, "input_tokens": 30880, "output_tokens": 2660}
2026-10-22T19:21:25Z [agent-out] PAY-2290 subscription charged twice: routed to disputes
2026-10-22T19:21:25Z [agent-out] KTESIO_USAGE {"sequence": 9, "input_tokens": 31570, "output_tokens": 3190}
2026-10-22T19:21:26Z [agent-out] PAY-2291 partial refund request: answered, closed
2026-10-22T19:21:26Z [agent-out] KTESIO_USAGE {"sequence": 10, "input_tokens": 29320, "output_tokens": 2870}
2026-10-22T19:21:27Z [agent-out] PAY-2292 SEPA mandate failed: routed to billing
2026-10-22T19:21:27Z [agent-out] KTESIO_USAGE {"sequence": 11, "input_tokens": 33060, "output_tokens": 3240}
2026-10-22T19:21:27Z [agent-out] PAY-2293 payout to wrong IBAN: needs a human
2026-10-22T19:21:27Z [agent-out] KTESIO_USAGE {"sequence": 12, "input_tokens": 30740, "output_tokens": 2980}
2026-10-22T19:21:28Z [agent-out] PAY-2294 dispute evidence due: routed to disputes
2026-10-22T19:21:28Z [agent-out] KTESIO_USAGE {"sequence": 13, "input_tokens": 32410, "output_tokens": 3150}
2026-10-22T19:21:29Z [agent-out] PAY-2295 receipt email bounced: answered, closed
2026-10-22T19:21:29Z [agent-out] KTESIO_USAGE {"sequence": 14, "input_tokens": 31890, "output_tokens": 3060}
2026-10-22T19:21:29Z [engine] engine: running -> paused (breach: cumulative dollars)
• note: Agent Instance 'pay-triage' is paused; no further output until it is resumed.
config · show
$ hekma agent config get pay-triage
▸ Effective config for pay-triage (4 rows)
Key                        Value         Validated  Source      
────────────────────────────────────────────────────────────────
budget.breach_action       pause         validated  instance    
budget.dollars.cumulative  2.00          validated  instance    
cost.rate.input            3.00          validated  instance    
cost.rate.output           15.00         validated  instance    

$ hekma agent show pay-triage
▸ Capabilities for pay-triage (OS: macos) (2 rows)
Capability    Support (curren…
──────────────────────────────
pause         guaranteed      
interaction   guaranteed      
▸ Runtime status for pay-triage (8 rows)
Field             Value                                           
──────────────────────────────────────────────────────────────────
State             paused                                          
Restart policy    on-failure                                      
Restart count     0                                               
Budget            cum $0.00/$2.00 (estimated) (pause)             
Usage (tokens)    cumulative in 468810 / out 44330 · $2.07 (estim…
Cost (estimated)  $2.07 (estimated)                               
Metering source   self-reported                                   
Supervision       detached                                        
• note: usage + budget are real TOKEN counts from the Usage Ledger (budget '—' means no budget configured); dollar figures appear only when a Rate is configured (cost.rate.input/output, optional cost.rate.cached) and are labeled estimates — with no Rate, dollar features are inert.

Illustration: 4 stand-in agents under hekma 0.11.0. The sidebar is drawn for this page; the panes show real hekma output.

what ships today

status

Supervised, like a service.

start, stop, pause and resume go through one state machine, so every agent moves and fails the same way. When a supervised process exits on its own, Hekma records the crash and the Restart Policy starts it again, backing off each time and giving up after five failures in a row.

Your fleet survives a reboot.

Fleet state and the usage ledger live in one SQLite database, and each agent’s config in its own Agent Home. When Hekma opens again it re-adopts every process whose pid and start time still match, and marks the rest failed with the reason. No phantom running rows.

Supervision runs while a hekma process holds the engine: a host that embeds it, or a command in your terminal. A long-running host, hekma serve, is on the main branch for the next release.

Metering you don't have to trust.

Point an agent’s OpenAI-compatible endpoint at Hekma and the engine meters its model traffic itself, through a proxy bound to 127.0.0.1. The counts come off the wire, not from the agent, so governance never depends on the agent’s cooperation.

Agents that report their own usage can do that too, and every instance shows which source its numbers come from.

Budgets, with the action you choose.

Set a token ceiling or a dollar cap, per run or cumulative, and choose what a breach does: warn, pause or stop. The check runs in the same code path that commits the usage, so the action fires on the event that crossed the line, not on the next poll.

In 0.11.0 the default action is pause; as Policies land, the default becomes warn with loud signals, and stopping stays opt-in. Dollars are always labelled estimates.

Any agent, one manifest.

An agent joins the fleet through a built-in kind or one adapter.toml: how to launch it, what it can do on each OS, and where its usage numbers come from. Agents that speak ACP (Agent Client Protocol), such as OpenCode and Hermes Agent, run through the built-in acp kind. Anything else you can start as a process registers the same way, and a conformance kit checks your adapter against the contract.

More from Ktesio

  • bite Native Apple apps for AI agents, over MCP. Calendar, Reminders, Mail, Notes, Contacts and Messages.
all projects on ktesio.dev

Start with the agents you run.

One command installs hekma and its short alias, hkm. Register the agents you already run and start them under supervision today; the rest of the control plane lands release by release.

curl -fsSL https://cli.ktesio.dev/hekma/install.sh | sh

Windows: irm https://cli.ktesio.dev/hekma/install.ps1 | iex Homebrew, Cargo and manual install