docs · start

Quickstart#

In about five minutes you register a small stand-in agent, give it a 6,000-token budget, start it, and watch Hekma count its tokens and pause it when the budget runs out. Every command and output on this page comes from a real run of Hekma 0.11.0 on macOS.

The stand-in is a shell script, so you need no API key and nothing is billed. When you are ready to run a real agent, Bring your own agent and Run an ACP agent take it from there.

Before you start#

You need:

  • Hekma 0.11.0 or later. If you do not have it yet, follow Install and check with hekma --version.
  • A POSIX shell. macOS and Linux have one. On Windows, run this page in WSL or Git Bash, because the stand-in agent is a sh script.
  • Two terminal windows. You will use the second one to watch the agent.

1. Write a stand-in agent#

Make a folder and save this script in it as agent.sh:

mkdir -p ~/hekma-quickstart/ticker
cd ~/hekma-quickstart/ticker
#!/bin/sh
# A stand-in agent: does a unit of work every two seconds and reports
# the tokens that work used.
n=0
echo "ticker ready"
while :; do
  sleep 2
  echo "finished task $n"
  echo "KTESIO_USAGE {\"sequence\": $n, \"input_tokens\": 1200, \"output_tokens\": 300}"
  n=$((n + 1))
done

Make it executable:

chmod +x agent.sh

The KTESIO_USAGE line is how an agent reports its own token use to Hekma: one line on stdout per unit of work, with a JSON object that says how many tokens went in and out. Each task here costs 1,500 tokens. Meter token usage explains the line in full.

2. Describe it in an adapter.toml#

An adapter tells Hekma how to launch an agent, what it can do on each operating system, and where its token counts come from. Save this as adapter.toml in the same folder, and replace the exec path with the absolute path to your agent.sh:

contract_version = "1.0.0"

[adapter]
kind = "ticker"
name = "Ticker"

[lifecycle.start]
exec = "/Users/you/hekma-quickstart/ticker/agent.sh"

[capabilities.pause]
linux = "guaranteed"
macos = "guaranteed"
windows = "best-effort"

[capabilities.interaction]
linux = "unsupported"
macos = "unsupported"
windows = "unsupported"

[metering]
source = "self-reported"

Use an absolute path for exec. Hekma starts the agent from its own folder, so a relative path such as ./agent.sh does not resolve. A bare program name works only if it is on your PATH.

The [capabilities] tables say that this agent can be paused on every OS and does not read input. source = "self-reported" tells Hekma to read the KTESIO_USAGE lines. The Adapter manifest reference lists every field.

3. Register the agent#

Point --manifest at the folder that holds adapter.toml, using an absolute path:

hekma agent register ticker --manifest ~/hekma-quickstart/ticker
✓ Registered Agent Instance ticker (ticker)
/Users/you/Library/Application Support/ktesio/agents/ticker
▸ Capabilities for ticker (OS: macos) (2 rows)
Capability    Support (curren…
──────────────────────────────
pause         guaranteed
interaction   unsupported

Hekma checked the manifest, created the agent's private folder (its Agent Home), and printed the capabilities that apply on your OS. If the manifest has a problem, Hekma names it and writes nothing; see Troubleshooting.

Use an absolute path here too. Hekma 0.11.0 remembers the manifest path exactly as you typed it and reads the manifest again at every start, so a relative path such as . works only when you run start from the same folder.

4. Give it a budget#

Cap the agent at 6,000 tokens in total, and pause it when it reaches the cap:

hekma agent config set ticker budget.tokens.cumulative 6000
hekma agent config set ticker budget.breach_action pause
✓ Set budget.tokens.cumulative = 6000 on Agent Instance ticker (instance layer)
✓ Set budget.breach_action = pause on Agent Instance ticker (instance layer)

At 1,500 tokens a task, the budget runs out after four tasks, about eight seconds after the agent starts. Budgets and cost covers per-run budgets, dollar caps and the other breach actions.

5. Start it detached#

hekma agent start ticker --detach
✓ Started Agent Instance ticker
running
• note: detached: the agent keeps running after this command exits, and the next `hekma` command re-adopts it. Until then it is NOT supervised: no crash detection, no budget enforcement, and no usage/event delivery happen between commands (supervision is command-scoped).

--detach keeps the agent running after the command returns. Without it, the agent would stop as soon as start exits, which is almost at once.

6. Watch it in a second terminal#

Open a second terminal and run:

hekma agent logs ticker --follow

The agent's output streams in. After four tasks the budget is spent, Hekma pauses the agent, and the follow ends on its own:

[hekma] ticker: adopted from a previous engine; metering resumes at the current end of the instance logs — any usage the previous engine still held in memory (its park) at its death is not recoverable and goes unaccounted
2026-10-22T19:05:49Z [agent-out] ticker ready
2026-10-22T19:05:49Z [engine] engine: starting -> running
• note: lines that follow may be un-attributed raw passthrough from agent.log: they were captured without a live engine tailer, so their timestamps are when this command read them, not when the agent wrote them
2026-10-22T19:06:23Z [agent-out] finished task 16
2026-10-22T19:06:23Z [agent-out] KTESIO_USAGE {"sequence": 16, "input_tokens": 1200, "output_tokens": 300}
2026-10-22T19:06:25Z [agent-out] finished task 17
2026-10-22T19:06:25Z [agent-out] KTESIO_USAGE {"sequence": 17, "input_tokens": 1200, "output_tokens": 300}
2026-10-22T19:06:27Z [agent-out] finished task 18
2026-10-22T19:06:27Z [agent-out] KTESIO_USAGE {"sequence": 18, "input_tokens": 1200, "output_tokens": 300}
2026-10-22T19:06:29Z [agent-out] finished task 19
2026-10-22T19:06:29Z [agent-out] KTESIO_USAGE {"sequence": 19, "input_tokens": 1200, "output_tokens": 300}
• note: Agent Instance 'ticker' is paused; no further output until it is resumed.
[hekma] ticker: the paused detached child was NOT resumed at engine release — it was paused by a BUDGET BREACH, and resuming it here would run it unsupervised in the enforcement-free between-commands window; it stays suspended until a later command resumes or stops it

The task numbers do not start at 0 in this run because the agent had been running for a while before the follow began. A follow streams the agent's new lines from its raw log as they are written, which is what the lines that follow may be un-attributed note says; lines written before the follow started are not replayed. Only the four tasks reported while the follow was open were counted, which is exactly the point of this step.

Why the follow matters. In Hekma 0.11.0 an agent is supervised only while some hekma command (or a program that embeds Hekma's engine) is running, so usage reported while no command runs is never counted and budgets are not checked. logs --follow keeps a command running beside the agent, which is what lets Hekma meter it and pause it live; Supervision and detached runs explains the model and the other patterns.

7. Inspect the agent#

Back in the first terminal, look at the fleet:

hekma agent list
▸ Fleet (1 row)
Name          Kind      State       Supervision  Restarts  Budget (tok, est. $)       Usage (tok, est. $)  Agent Home
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
ticker        ticker    paused      detached     0         cum 0/6000 tok (pause)     in 4800 / out 1200   /Users/you/Library/…
Fleet total: in 4800 / out 1200 · — (no Rate configured — dollars not derived)

The agent is paused, and the budget cell reads cum 0/6000 tok (pause): 0 tokens left of a 6,000-token cumulative budget, with the pause action. Usage is 4,800 tokens in and 1,200 out, four tasks' worth. There is no dollar figure because you have not set a rate.

For one agent in detail, use show; for its token totals, use usage:

hekma agent show ticker
hekma agent usage ticker
▸ Capabilities for ticker (OS: macos) (2 rows)
Capability    Support (curren…
──────────────────────────────
pause         guaranteed
interaction   unsupported
▸ Runtime status for ticker (8 rows)
Field             Value
──────────────────────────────────────────────────────────────────
State             paused
Restart policy    on-failure
Restart count     0
Budget            cum 0/6000 tok (pause)
Usage (tokens)    cumulative in 4800 / out 1200; this run: in 480…
Cost (estimated)  — (no Rate configured — dollar features inert)
Metering source   self-reported
Supervision       detached
...
▸ Usage for ticker (5 rows)
Field               Value
──────────────────────────────────────────────────────────────────
Cumulative tokens   in 4800 / out 1200
Cumulative cost     — (no Rate configured — dollar features inert)
Current-run tokens  in 4800 / out 1200
Current-run cost    — (no Rate configured — dollar features inert)
Metering source     self-reported

Each of these commands also prints a few lines on stderr: the adoption note you saw above, and a reminder that usage figures are token counts from the usage ledger. Add --json to list, show or usage for output a script can parse; see Logs, JSON and scripting.

The paused agent stays paused between commands, so it cannot spend past its budget while nobody is watching. hekma agent resume ticker lets it run again, but the cap that fired does not fire again in this run, even if you raise it; Budgets and cost shows how to carry on under a new limit.

8. Stop and remove it#

hekma agent stop ticker --timeout 3
hekma agent remove ticker --delete
✓ Stopped Agent Instance ticker
stopped
✓ Agent Instance ticker removed (Agent Home deleted)

--timeout 3 gives the agent three seconds to exit before Hekma forces it (the default is 30). --delete also deletes the Agent Home; without it, Hekma keeps the folder. You can delete ~/hekma-quickstart too.

What you did#

You ran the whole Hekma loop: an adapter describes the agent, register adds it to the fleet, config set gives it a budget, start --detach runs it, a long-running logs --follow keeps it supervised, and Hekma pauses it when its usage reaches the budget.