Record a run
nika run renders a live storyboard for humans and writes an execution
journal by default to .nika/traces/<timestamp>-<id>.ndjson. The
verdict line prints that path — the same file
nika compile hello hello.nika then nika run hello.nika writes.
Add --json and the same run also streams machine events on stdout, one
NDJSON line per event — the CI and agent surface (stdout stays pure
NDJSON; nothing else is printed there):
--resume, nika trace show|replay|verify and the editor read the
journal directly. With no path, show, replay, and verify read the
workspace’s latest journal and name it on stderr
(nika trace: reading <path> (the workspace latest)). Pass a path to
select another; nika trace ls lists the store. Opt out per run with
--no-trace-file, or globally with NIKA_NO_TRACE_FILE (nika try
never journals — the mock rehearsal is not a workspace run).
A refusal before execution or a queued cancellation can leave no journal.
Interruption can leave incomplete evidence. A job or receipt identity alone
does not prove that a trace exists or is sealed; nika trace verify reads
existing evidence and never seals it.
The journal keeps task outputs verbatim so a run can be replayed and
verified. Hash-chained is not confidential: .nika/traces/ inherits the
sensitivity of whatever the workflow read, and on a shared or CI machine
that directory is a second data-at-rest surface. Treat it like the files
the run opened. A redaction posture that still verifies is a larger
conversation; this page only names the consequence.
The event stream
A trace is the run’s lifecycle spine. Each line is one event with a unique id, a nanosecond timestamp, akind, and typed fields:
workflow_started, then onetask_scheduledper tasktask_startedwhen a task’s dependencies cleartask_completed(withduration_ms), ortask_failed, ortask_skipped(awhen:gate said no), ortask_cache_hit(a resumed run reused this task’s recorded work)workflow_completed, orworkflow_failed, orworkflow_paused(a human gate is waiting — the trace carries the prompt payload)
nika 0.123.0: the one-task mock/echo hello of the
SDK quickstart, with each event’s fields abridged.
Every line carries chain, the hash that links it to the line before:
run_sealed, closes the journal.
The spine is not the whole vocabulary. Deeper kinds record retries
(task_retrying), cancellation (task_cancelled,
workflow_cancelled), money (cost_incurred), security checks
(permit_checked), streaming (infer_chunk) and the agent loop
(agent_tools_selected, agent_budget_checkpoint, and friends). The
event kinds of engine are listed in
Concepts · Events.
Real spend also rides the spine: a priced task_completed carries a
cost_usd field next to its tokens — absent for mock and local
runs (unpriced is honestly absent, never a fake 0). Agent loops
report the loop’s accumulated tool spend as tools_cost_usd.
A file that declares run.access or run.reasoning also journals what it
asked and what its route did. access_requirement, the declaration, rides
workflow_started and the terminal event of each infer: or agent: task.
access_selection rides that terminal event once the task reached its route:
for the model, the effort and a declared service tier, the value asked, the
value sent and the value read back, kept apart
(Harness access).
A file that declares neither journals neither.
Harness tasks in the journal
A task on an agent application you are signed into (a harness seat) runs that application’s own tools, so its journal records what Nika judged rather than each tool call:- one
permit_checkedper permission the application asked, with its gate and the decisionallow,denyorescalate. A Codex command that asks to leave its sandbox readssandbox · commandand always escalates, whateverpermits.execgrants: the run pauses with the command and Codex’s reason on one sanitized line, and the task’s decisions are journaled just beforeworkflow_paused; - a turn the application reports as failed (a rejected model, an exhausted
retry limit) as
task_failedwithNIKA-1804(transient, soretry:may replay it) orNIKA-1805, never as atask_completedwhose output is the error text; - one
agent_image_observedper image the seat sent, with the digest of the received bytes and, underimages: { save: }, thesaved_pathNika wrote.
Replay, never re-execute
Two commands inspect a recorded run. With no path they read the workspace’s latest journal:replay plays the recorded events through the same renderer that drew
the original run: same storyboard and verdict card, with time compressed 6×
by default (--speed).
show skips the animation and prints the summary. Both are a
reading of the file — they do not walk the hash chain.
Tamper-evidence · every event, hash-chained
The trace is not just a log — it is a hash chain. Every event the engine emits carries a link over the one before it: task boundaries, each permit check, every tool call anagent: loop makes, the run seal
at the end. Nothing the engine did is off the chain, and nothing can be
edited, reordered, or dropped from the middle without breaking it.
Change one byte, and verify says where. Each line of a run’s trace carries the sha256 of the line before it. nika trace verify reads the chain back intact; in a copy with one byte of line 4 changed, it stops at line 5 with BROKEN and exit code 2. A mock/echo rehearsal captured from the real CLI on nika 0.121.0; the scan and the moving hashes are illustration.
verify walks the chain and then climbs a proof ladder, reporting the
highest tier honestly attained. That is the proof, distinct from
show / replay: those inspect the recorded events; this command
attests the sequence is intact. The tiers:
- OK — the links hold; the sequence is intact (
verifyprintsOK — N events · chain intactand the head to compare). An unsigned run stops here and saysUNSEALED. - SEALED — a signature over the whole chain verifies against a
custody key (the run was signed).
verifyweighs the public keys in the order a run signs, the keychain aside, after--key: the public half of the explicitNIKA_RUN_KEY_FILE·NIKA_RUN_PUB_FILEpair, when both variables are set, then~/.nika/keys/run-signing.pub, then the retired-key ledger (~/.nika/keys/retired.pub). A journal sealed with an explicit pair therefore verifies without--keywherever the same two variables are set. - ANCHORED — a detached sidecar verifies fully offline against a
public transparency log entry + an RFC 3161 timestamp (
nika trace anchoris the opt-in network act that mints it). - REPLAYED — you passed a separately supplied fresh journal; verify compares it. The command never starts that second run.
traceVerify / nika trace verify verifies an existing seal. It
does not create one. A succeeded run can still be UNSEALED on a keyless
machine. An intact chain is not proof that a human read the output, that
an external API committed, or that the business goal was met.
Refusals name themselves rather than hide in a tier:
--sealed and --anchored make a missing tier an error (exit 3), a
--replay divergence is exit 2, and --json prints one machine document
per trace (verify_version: 1). nika trace verify --help lists the same
exits.
Why this matters
- The run is auditable. Which tasks ran, in what order, how long each took, what it cost, which permits were checked: it is all in the file, not in someone’s scrollback.
- The run is verifiable. Every event is hash-chained and the whole
chain verifies offline (
nika trace verify) — tamper-evident by construction, not by trust. - The run is shareable. Attach the
.ndjsonto a PR or an issue. A reviewer replays it locally and sees exactly what you saw, without credentials and without re-running anything. - The demos are honest. The replays on nika.sh (“Press play. It really ran.”) are exactly these files: recorded runs played back through the same renderer, not screenshots and not mockups.
- The run is resumable. The same file doubles as the checkpoint:
nika run --resume <trace>skips completed work with visible cache hits and re-arms a paused human gate. See Resume a run.
Related
- Reference · CLI: every
nika runandnika traceflag, including--jsonand--output json(the typedoutputs:export, a different surface from the event stream). - Concepts · Events: the full event vocabulary and the durability model behind it.
- Concepts · Workflows: how a file becomes the executed graph the trace records.