docs · reference
Adapter manifest#
An adapter.toml file tells Hekma how to run any program as an agent: the command that starts it, what it can do on each OS, where its token counts come from, and how config keys reach it. This page is the field reference; Bring your own agent walks through writing one.
You register a manifest with hekma agent register NAME --manifest DIR, where DIR holds adapter.toml (or point at the file itself). Hekma parses and checks the whole file before writing anything. Unknown fields are rejected, so a typo fails registration instead of being ignored, and the error names the section at fault.
Complete example#
contract_version = "1.0.0"
[adapter]
kind = "worker"
name = "Worker"
[lifecycle.start]
exec = "/usr/local/bin/worker"
args = ["--serve"]
env = { LOG_LEVEL = "info" }
[capabilities.pause]
linux = "guaranteed"
macos = "guaranteed"
windows = "best-effort"
[capabilities.interaction]
linux = "guaranteed"
macos = "guaranteed"
windows = "guaranteed"
[metering]
source = "self-reported"
[interaction]
channel = "stdio"
[config.model]
env = "MODEL"
[config."memory.dir"]
env = "WORKER_MEMORY_DIR"| Section | Required | Purpose |
|---|---|---|
contract_version | yes | The adapter contract version the file is written for. |
[adapter] | yes | The adapter's kind and display name. |
[lifecycle] | yes, with start | How to launch the agent. |
[capabilities] | yes | What the agent supports on each OS. |
[metering] | yes | Where token counts come from. |
[interaction] | no | Which input channel the agent uses. |
[config] | no | How config keys reach the agent. |
Hekma reports the first required section that is missing or invalid.
contract_version#
The version of the adapter contract the manifest targets. Hekma 0.11.0 speaks 1.0.0, so write:
contract_version = "1.0.0"The value must be a full X.Y.Z version: 1.0, 1 and v1.0.0 are rejected. A suffix such as 1.0.0-rc.1 is accepted. Hekma loads a manifest only when its major version matches its own; the minor and patch parts are not compared. A mismatch fails registration with exit code 1 and names both versions:
✗ The adapter manifest at '/Users/you/agents/worker/adapter.toml' cannot load: incompatible adapter contract: manifest declares 2.1.0, engine speaks 1.0.0 — compatible iff the major versions match (contract v1 policy, docs/adapter-contract.md#versioning). Ask the adapter author to retarget the manifest's contract_version to this engine's contract major — see docs/adapter-contract.md.Versions 0.x are rejected too. See Versioning for the full rule.
[adapter]#
| Field | Type | Required | Meaning |
|---|---|---|---|
kind | string | yes | The adapter's identifier, shown in the Kind column. Lowercase letters, digits, - and _, starting with a letter or digit. |
name | string | no | A display name. |
[lifecycle]#
[lifecycle.start] is required. It is the command Hekma runs to start the agent.
| Field | Type | Required | Meaning |
|---|---|---|---|
exec | string | yes | The program: a name found on PATH when the agent starts, or an absolute path. |
args | list of strings | no | Its arguments. Default none. |
env | table of strings | no | Extra environment variables. Default none. |
The agent runs with its Agent Home as its working directory and inherits the environment of the hekma command that started it, plus env and any mapped config. A config mapping that sets the same variable as env wins, and Hekma prints a note saying so at start.
Hekma copies the start command when you register. Editing adapter.toml later does not change an agent that is already registered; remove it and register it again.
You may also write [lifecycle.stop], [lifecycle.pause] and [lifecycle.resume] with the same three fields. Hekma 0.11.0 checks them but never runs them. Stopping is always done by signal: SIGTERM to the agent's process group on Unix, then SIGKILL after the stop timeout; on Windows Hekma waits out the timeout and then ends the process's job. Pausing uses SIGSTOP and SIGCONT where the capabilities say guaranteed.
An agent should therefore exit cleanly on SIGTERM. An agent that exits on its own while running, even with code 0, counts as a crash and is handled by the restart policy. An agent that exits within the first 300 milliseconds fails the start instead.
[capabilities]#
The capability declaration: one table per capability, rating it per OS.
[capabilities.pause]
linux = "guaranteed"
macos = "guaranteed"
windows = "best-effort"| Capability | What it governs |
|---|---|
pause | hekma agent pause and resume, and the pause breach action. |
interaction | Whether the agent gets a stdin pipe and accepts hekma agent send. |
Each table takes the keys linux, macos and windows, each set to one of:
| Level | Meaning |
|---|---|
guaranteed | Hekma relies on it. A pause really suspends the process. |
best-effort | Hekma does it, and labels the result as cooperative. On Windows, pause is never stronger than this. |
unsupported | The command fails at once with exit code 5, quoting the declaration. |
An OS left out of a table counts as unsupported. The manifest must declare at least one capability that is not unsupported on some OS, or registration fails.
Declare interaction supported only if the agent reads stdin. An agent with interaction support gets a stdin pipe when started without --detach; one without it gets a closed stdin, so it never blocks reading input that will not arrive.
[metering]#
Where the agent's token counts come from, its metering source.
[metering]
source = "self-reported"source | How usage is counted |
|---|---|
self-reported | The agent prints a usage line on stdout for each model call (below). |
engine-observed | Hekma runs a proxy on 127.0.0.1 and reads token counts from the model provider's responses. Map metering.base_url in [config] so the agent sends its requests to the proxy, and set metering.upstream_base_url on the agent. Such an agent cannot be started with --detach. |
A self-reporting agent prints one line per usage event to stdout, starting with KTESIO_USAGE and a space, then a JSON object with sequence, input_tokens, output_tokens and optionally cached_tokens:
KTESIO_USAGE {"sequence": 0, "input_tokens": 1200, "output_tokens": 300, "cached_tokens": 400}Hekma adds the agent name, run, source and time itself, and counts each sequence once per run. A line that breaks the format is skipped without stopping the agent. Self-reported usage is the full reference for the fields and rules; Meter token usage covers both sources step by step.
[interaction]#
Optional. Names the channel the agent takes input on.
| Field | Type | Meaning |
|---|---|---|
channel | "stdio" or "http" | stdio: the agent reads stdin. http: the agent takes input over its own HTTP API. |
The field is descriptive in 0.11.0: Hekma behaves the same for both values. Whether the agent gets a stdin pipe depends on the interaction capability, and hekma agent send always writes to stdin. An HTTP-only agent can declare http so the manifest describes it accurately, but send will not reach it. Any other value is rejected.
[config]: config key mapping#
Optional. Maps config keys to the agent's own settings, so the same key works for every agent. Each [config.KEY] table names exactly one target:
# As an environment variable.
[config.model]
env = "MODEL"
# As a command-line flag: appended as two arguments, --model <value>.
[config.model]
flag = "--model"
# As a value in a TOML file in the Agent Home, at a dotted key.
[config.model]
file = { path = "config/agent.toml", key = "llm.model" }(Pick one; a key can have only one target.)
| Target | Rules |
|---|---|
env = "NAME" | The variable is set in the agent's environment. |
flag = "--name" | The flag and the value are appended to [lifecycle.start] args. |
file = { path, key } | Hekma writes a TOML file at path, relative to the Agent Home, with the value at the dotted key. path may not be absolute or contain ... Several keys mapped to the same file are written to one document. |
Keys a mapping can name:
- Any key on Config keys, such as
model. A key nobody sets is simply not delivered. - The reserved key
memory.dir: the path of the agent'smemory/folder when afilesystemmemory backing is attached. Quote it:[config."memory.dir"]. Without this mapping the folder is still kept, but the agent is not told where it is, and Hekma says so on stderr at start. - The reserved key
metering.base_url: the proxy address forengine-observedmetering, usually mapped to the variable the agent reads its API base URL from, such asOPENAI_BASE_URL.
You do not map agent.* keys: Hekma always passes agent.NAME as the environment variable NAME.
Things to know when you write mappings:
- Secrets. A
secret:NAMEvalue is delivered in clear text to the target. Preferenvorfilefor secrets. Aflagputs the secret on the command line, where other local users can read it; Hekma warns when that happens. - JSON-configured agents. The
filetarget writes TOML only. For an agent that reads JSON config, map a key to the environment variable it reads whole config from (for example OpenCode'sOPENCODE_CONFIG_CONTENT). - Placeholders. If the agent fills
{env:VAR}placeholders in its own config and treats a missing variable as empty, make sure every such variable is mapped and set, or the agent will run with an empty value without warning. - Self-updating agents. Map the agent's setting that turns off self-update, so the version you tested is the one that runs.
- Isolation. If several agents of the same program share a machine, map the settings that move the program's data and config folders into each Agent Home (for example
XDG_DATA_HOMEandXDG_CONFIG_HOMEfor XDG-based programs). The adapter contract lists these duties.
Read next#
- Bring your own agent: write and register a manifest step by step.
- Adapter contract and conformance kit: the rules a manifest promises to follow, and how to test it.
- Config keys: the keys a
[config]section can map. - Meter token usage: set up either metering source.