docs
Hekma docs
Hekma is the control plane for agent workloads: one way to run, see and steer any agent, from a coding agent on your laptop to CrewAI and LangGraph flows in production, built so that it is never the reason prod stops. It is an open-source Rust CLI and engine.
Today, Hekma supervises, meters and budgets the agents you run: it starts, stops, pauses and restarts them, counts the tokens they spend, and acts when they cross a token or dollar budget. The rest of the control plane (Runs, Policies, Run Keys and wire control) is being built in the open.
These docs describe Hekma 0.11.0, released on 17 October 2026. Features only on Hekma's main branch are marked Unreleased: after 0.11.0, and pages about what is still being built are tagged in development or planned.
Choose a path
- Try it in five minutesInstall Hekma, run a small agent under supervision, and watch it meter the tokens it spends.
- Run the agents you useConnect OpenCode, Hermes Agent or any program with a built-in kind or an adapter.toml.
- See where Hekma is goingRuns, Policies, Run Keys and wire control: the control plane being built in the open.
- Build on the engineEmbed hekma-engine in a Rust program for always-on supervision and events.
Hekma in one minute#
# Install hekma (and its short alias, hkm).
curl -fsSL https://cli.ktesio.dev/hekma/install.sh | sh
# Describe the agent once, and give it a budget.
hekma agent register my-agent --manifest ~/agents/my-agent
hekma agent config set my-agent budget.tokens.cumulative 500000
# Run it in the background, and watch it: metering and budgets run live.
hekma agent start my-agent --detach
hekma agent logs my-agent --followEach command is explained in the Quickstart, which uses a small stand-in agent so you can run it as is.
What Hekma does today#
| Area | What you get |
|---|---|
| Lifecycle | start, stop, pause and resume any agent through one state machine. Crashes are recorded and restarted with backoff. State survives a reboot. Concepts |
| Metering | Counts the input, output and cached tokens each agent spends, either reported by the agent or read off the wire by a local proxy. Meter token usage |
| Budgets | Token and dollar ceilings, per run or cumulative, with a pause, stop or warn action applied at the usage event that crossed the line. Budgets and cost |
| Any agent | A built-in acp kind for Agent Client Protocol agents, and an adapter.toml manifest for anything else you can start as a process. Supported agents |
| The gallery | One page per agent that runs under Hekma today, with an honesty table for each, and a recipe for running one budget-capped in CI. Adapter gallery · Agents in GitHub Actions |
| Observability | Export token usage, budget breaches, derived cost and lifecycle state to any OpenTelemetry collector over OTLP/HTTP+JSON — opt-in, metrics-only, nothing leaves without an endpoint. Telemetry export |
| Scripting | Versioned JSON output and stable exit codes on every command. Logs, JSON and scripting |
| Embedding | The engine is a Rust library with an event stream, so your own program can run the whole fleet. Embed the engine |
What is being built#
These are not in 0.11.0. Each links to a page tagged with its stage; the roadmap has the order.
| Area | What it will give you |
|---|---|
| Runs (in development) | Every supervised agent, and the work a Host opens inside one, becomes a Run with an id, labels, a status and a Control Depth, listed exception-first by hekma ps. Runs Hekma did not start follow (planned). Runs, Control Depth, ps and top |
| Policies (in development) | Standing limits matched by label, with warn as the default Breach Action and loud signals instead of a stopped run. Policies and the warn default |
| Run Keys (planned) | A per-Run key in the agent's API-key slot, so the provider key never leaves Hekma and no call goes unattributed. Run Keys and key custody |
| Attach and wire control (planned) | Framework flows join through the proxy, a header or OpenTelemetry; hold, reroute or reject a Run's next model call. Attach and wire control |
What Hekma does not do#
- It is not an agent framework. Hekma runs agents other people wrote, or you wrote, as processes. It does not help you build one.
- It is not a sandbox. Each agent gets its own folder, but runs with your user's permissions.
- The CLI supervises only while a command runs. In 0.11.0, a detached agent is metered and held to its budget only while some
hekmacommand, or a program embedding the engine, is running. Supervision and detached runs shows how to keep one running. - Its costs are estimates. Dollar figures come from rates you set, not from your provider's bill.
- It is not a model gateway. It does not compete with LiteLLM or Portkey; the control plane is being built to sit beside them and tag every call with its Run.
- It is not another dashboard. Hekma feeds the observability stack you already run (OTLP export is on main, unreleased); its own surfaces are the CLI and the Control API.
Read next#
- Quickstart: run a first agent and watch its budget pause it.
- Concepts: the handful of terms the rest of the docs use.
- Supervision and detached runs: when Hekma is watching your agents in 0.11.0.
- Status and roadmap: what ships, and what the control plane adds next.
All docs
Start
Install Hekma, run a first agent, and learn the handful of ideas everything else builds on.
- InstallInstall Hekma on macOS, Linux or Windows, check it works, keep it updated, and remove it.
- QuickstartRun your first supervised agent in five minutes: register it, give it a budget, start it, and watch Hekma meter and pause it.
- ConceptsThe ideas behind Hekma in one page: agents, adapters, the fleet, runs, supervision, metering, budgets and where state lives.
- TroubleshootingFix common Hekma problems by phase: install, register, start, usage and budgets, ACP agents and updates, with the exact messages you see.
Control plane
Where Hekma is going: Runs, Policies, Run Keys and wire control. Each page is tagged in development or planned, and may change before it ships.
- Runs, Control Depth, ps and top in developmentEvery agent workload as a Run with an id, labels, a status and a Control Depth, listed with hekma ps, steered by Selector and watched with hekma top. In development.
- Policies and the warn default in developmentStanding limits that apply to every Run a Selector matches, and warn as the default Breach Action. In development.
- Run Keys and key custody plannedHow Hekma will give each Run its own credential in place of your provider key, keep the real key itself, and flag calls that go around it. Planned.
- Attach and wire control plannedBring agents Hekma does not launch under control with little or no code, and hold, release, reroute or reject their model calls. Planned.
Guides
Task by task: connect your agents, meter them, budget them, and run them unattended.
- Run an ACP agentRun any Agent Client Protocol agent, such as OpenCode or Hermes Agent, under Hekma with the built-in acp kind.
- Bring your own agentWrite an adapter.toml for a program you already run: how to launch it, what it supports, how it reports tokens, how config reaches it, and how to test it.
- Supervision and detached runsWhen Hekma is watching your agents, what --detach changes, and how to keep budgets enforced while agents run.
- Meter token usageHow Hekma counts an agent's tokens: self-reported usage lines or the engine-observed proxy, how to set each up, and what is not counted.
- Budgets and costCap an agent's tokens or estimated dollars per run or in total, choose what happens on a breach, and resume an agent after one.
- Config, secrets and memorySet agent configuration in layers, keep API keys out of Hekma's output with secret references, and give agents durable memory.
- Logs, JSON and scriptingRead and follow agent logs, get JSON from Hekma commands, and use stdout, stderr and exit codes safely in scripts and CI.
- Run Hekma as a service unreleasedRun hekma serve as a long-running host on a server or in a container. Unreleased: after 0.11.0.
- Agents in GitHub Actions unreleasedRun a budget-capped agent in CI: a checksum-verified release binary, a token ceiling with a breach action, a wall-clock-bounded job, usage rendered into the job summary, and exit-code honesty. Unreleased: after 0.11.0.
- Upgrade from ktMove from the older Ktesio kt command (v0.1.1 to v0.7.0) to Hekma: what changed, the data guarantee, steps per install channel, and the environment map.
Reference
Exact facts to look up: every command, key, JSON field, exit code and manifest field.
- CLI referenceEvery hekma command with its arguments, flags, output and the most common errors.
- Config keysEvery configuration key Hekma knows: budgets, rates, metering, ACP launch settings and reserved keys.
- JSON outputThe machine-readable documents hekma prints with --json, their schema versions and their fields.
- Exit codes and environmentThe exit codes every hekma command returns and the environment variables Hekma reads or sets.
- Adapter manifestThe adapter.toml reference: every section and field an agent manifest can declare.
- Adapter contract and conformance kitThe versioned contract between Hekma and agent adapters, how versions are negotiated, and how to test an adapter with the conformance kit.
- Supported agentsWhich agents Hekma runs today, how each one connects, and the versions each was tested with.
- Control API unreleasedThe local HTTP and JSON API that hekma serve can expose. Unreleased: after 0.11.0.
- Telemetry export (OTLP) unreleasedThe opt-in OTLP/HTTP+JSON metrics exporter: the three flags, the versioned otlp-metrics v1 exposition, and the honest limits of v1. Unreleased: after 0.11.0.
Adapters
The adapter gallery: which agents run under Hekma today, each with an honesty table of what is proven and what is only characterized.
- Adapter Gallery unreleasedThe validated index of agents that run under Hekma today: a per-capability honesty table for each, an evidence class for every claim, and the re-validation duty per entry. Unreleased: after 0.11.0.
- Hermes Agent unreleasedHermes Agent under Hekma: run-verified through its native hermes-acp entry point, with billing-grade self-reported metering. Unreleased: after 0.11.0.
- opencode unreleasedopencode under Hekma: run-verified through its native ACP server (opencode acp), with honest context-grain-only metering. Unreleased: after 0.11.0.
- Gemini CLI unreleasedGemini CLI under Hekma: ACP through its documented --experimental-acp flag; smoke-listed and characterized, not run-verified with a pin. Unreleased: after 0.11.0.
- GitHub Copilot CLI unreleasedGitHub Copilot CLI under Hekma: ACP through its --acp --stdio server mode (public preview); characterized from upstream docs, not run-verified here. Unreleased: after 0.11.0.
- Cursor CLI unreleasedCursor CLI under Hekma: ACP through its agent acp subcommand (a hidden/advanced surface); characterized from upstream docs, not run-verified here. Unreleased: after 0.11.0.
- goose unreleasedgoose under Hekma: ACP through its goose acp subcommand (experimental upstream); characterized from upstream docs, not run-verified here. Unreleased: after 0.11.0.
- Claude Code unreleasedClaude Code under Hekma: through a third-party ACP adapter binary; Hekma ships no such adapter, and the supply-chain decision is the operator’s. Unreleased: after 0.11.0.
- Codex unreleasedCodex under Hekma: through a third-party codex-acp adapter binary; characterized from upstream docs, not run-verified here. Unreleased: after 0.11.0.
- Crush unreleasedCrush under Hekma: through an unofficial third-party crush-acp adapter binary; characterized, not run-verified here. Unreleased: after 0.11.0.
- Aider unreleasedAider under Hekma: a manifest adapter with engine-observed metering through the OPENAI_API_BASE override; the shipped manifest is conformance-validated in CI. Unreleased: after 0.11.0.
Embedding
Drive the engine from your own Rust program, with no CLI in between.
- Embed the engineUse hekma-engine as a Rust library to supervise, meter and budget agents from your own program.
- Events, resync and diagnosticsSubscribe to the engine's events, recover missed events after a crash, and route engine diagnostics into your own logs.
How it works
The design underneath: crates, supervision, the metering proxy and the state on disk.
- ArchitectureHow Hekma is built: the crates, the engine, process supervision on each OS, the metering proxy, and the state on disk.
- Metering agents you don’t controlWhy Hekma meters an agent’s model traffic where the agent cannot bypass it, how the proxy, the usage ledger and budgets fitted together in September 2026, and what the meter could not see then.
Project
Where Hekma stands, what changed in each release, and how to contribute.
- Status and roadmapWhat Hekma does today, what is on main but unreleased, the control-plane roadmap, and how versions and deprecations work.
- Release notesWhat changed in each Hekma release, with download links and upgrade notes.
- ContributingHow to build Hekma from source, run the tests, and send a pull request.