Config keys#

This page lists every config key Hekma 0.11.0 accepts, with its type, default and validation. You set keys per agent with hekma agent config set; Hekma knows fourteen keys (two of them reserved for its own use), and any other key must start with agent.. Budget and price keys take effect on the next usage event; the rest take effect at the agent's next start.

How keys work#

A key is a dotted path such as budget.tokens.cumulative. Hekma stores each agent's keys in config.toml in its Agent Home, so setting budget.tokens.cumulative to 6000 writes cumulative = "6000" under a [budget.tokens] table. config set stores every value as text. You can edit the file by hand, but config set checks keys and values first and writes the file in one step.

A key reaches the agent only if the agent's adapter maps it to an environment variable, a command-line flag or a file. A known key the adapter does not map is accepted and does nothing for that agent. The manifest [config] section is where a manifest adapter declares its mappings.

Any value may be a secret reference, secret:NAME. Hekma stores the reference, resolves it when the agent starts, and masks it everywhere it displays it. See Config, secrets and memory.

All keys#

An unknown key outside agent. is rejected with exit code 2, and the error suggests the nearest known key:

$ hekma agent config set worker modle gpt-4o
✗ unknown config key 'modle'; did you mean 'model'?. Set a known unified key, or use the agent.* pass-through namespace for agent-native extras (e.g. hekma agent config set <name> agent.<key> <value>).

model#

The model the agent should use, as a free string. Hekma does not check the value. It reaches the agent only through the adapter's mapping: the mock kind maps it to the MODEL environment variable, a manifest maps it however its [config.model] section says, and the acp and hermes kinds do not map it (configure the model in the agent itself).

hekma agent config set worker model gpt-4o-mini

Budgets#

Budgets cap an agent's tokens or estimated dollars, per run or over its whole life (cumulative). Hekma checks them each time it writes a usage event to the usage ledger, so they apply only while the agent is supervised.

hekma agent config set worker budget.tokens.cumulative 500000
hekma agent config set worker budget.breach_action stop

An invalid value is rejected before anything is written, with exit code 1:

$ hekma agent config set worker budget.breach_action halt
✗ invalid value 'halt' for config key 'budget.breach_action': 'halt' is not a valid breach action (expected one of: pause, stop, warn). Nothing was changed. Fix the value and try again.

One breach action covers token and dollar budgets alike. Each budget breaches at most once per run. When a token budget and a dollar budget cross on the same usage event, the token breach drives the action and both are recorded. Budgets and cost walks through breaches and what to do after one.

Rates#

A rate is your price per million tokens. With a rate set, Hekma derives an estimated cost for each usage event, shows it in list, show and usage, and enforces dollar budgets.

Write dollar amounts as plain decimals: 3, 3.00, 0.30 or .5. They must not be negative, carry a sign or currency symbol, or have more than six decimal places (Hekma counts money in whole micro-dollars, $0.000001). A bad amount exits with code 1 and changes nothing.

hekma agent config set worker cost.rate.input 3.00
hekma agent config set worker cost.rate.output 15.00
hekma agent config set worker cost.rate.cached 0.30

Both cost.rate.input and cost.rate.output must be set for any dollar figure to appear; with only one, the rate is ignored and costs read —. When cost.rate.cached is unset, cached tokens are priced at the input rate, which can only overstate the cost. Each usage event keeps the rate that applied when it was recorded, so changing a rate later does not reprice past usage.

metering.upstream_base_url#

The real model provider endpoint for an agent whose metering source is engine-observed, for example https://api.openai.com/v1 or http://127.0.0.1:1234 for a local gateway. At start, Hekma runs a proxy on 127.0.0.1, points the agent at it through the reserved metering.base_url key, forwards each request to this URL and reads the token counts from the responses.

The value must be an http:// or https:// URL. An engine-observed agent without it fails to start, and nothing changes. Setting it on an acp agent opts that agent into observed metering: the acp kind passes the proxy address as OPENAI_BASE_URL. See Meter token usage.

acp.command and acp.args#

The launch command for an acp agent. acp.command is required: starting an acp agent without it fails with exit code 1 and an error naming both keys. acp.args is optional.

hekma agent config set coder acp.command opencode
hekma agent config set coder acp.args acp

Other kinds ignore these keys. See Run an ACP agent.

agent.* pass-through keys#

Any key that starts with agent. is accepted without validation and delivered to the agent as an environment variable named by the rest of the key, exactly as written. agent.OPENAI_API_KEY becomes OPENAI_API_KEY; agent.log_level becomes log_level. This works for every kind and needs no mapping in the adapter.

hekma agent config set worker agent.OPENAI_API_KEY secret:OPENAI_API_KEY
hekma agent config set worker agent.LOG_LEVEL debug

config get marks these keys unvalidated. Pass-through variables are applied before the adapter's own mappings, so if both set the same variable, the mapped value wins.

Reserved keys#

Two keys exist so that adapters can map them, but Hekma sets their values itself at each start. Do not set them.

config set accepts both keys in 0.11.0. A hand-set memory.dir is removed at start and never reaches the agent. A hand-set metering.base_url is replaced by the proxy address when Hekma runs a proxy; for any other agent it is passed through the adapter's mapping as written, so leave it unset. Neither engine-set value is written to effective-config.json.

Restart policy#

The restart policy is not a config key. config set worker restart.policy never is rejected as an unknown key. Each agent's policy is stored with its process record, defaults to on-failure, and can be changed only through the engine API (set_restart_policy) from a program that embeds the engine. hekma agent show and --json output show the current policy.

A crash is the process exiting on its own while running, including an exit with code 0. Only an operator start resets the consecutive count to 0; a restarted agent that runs cleanly for a while keeps its count. Restarts happen only while a process holds the engine open, so between CLI commands a detached agent that crashes is noticed by the next command.

Layers and provenance#

Each value resolves from four config layers, weakest first. A stronger layer's value replaces a weaker one key by key.

Because the two default layers are empty in 0.11.0, every value you see from the CLI comes from the instance layer, and a key with no value there is unset. Defaults such as the pause breach action are built into Hekma's behaviour, not stored in a layer, so config get does not list them.

hekma agent config get shows the winning layer in its Source column, and --json puts it in each entry's source field:

$ hekma agent config get worker
▸ Effective config for worker (3 rows)
Key                       Value         Validated    Source
─────────────────────────────────────────────────────────────────
agent.api_key             secret:****   unvalidated  instance
budget.tokens.cumulative  6000          validated    instance
model                     gpt-4o-mini   validated    instance

At each start, Hekma writes the resolved config, with secrets masked and the reserved keys left out, to effective-config.json in the Agent Home. That file is a record of what the last start used; editing it changes nothing.

Read next#

• Config, secrets and memory: setting keys, secrets and memory step by step.
• Budgets and cost: how budgets and rates behave in practice.
• Adapter manifest: how an adapter maps keys to its agent.
• JSON output: the config get --json document.