mock/echo model, which makes no model
call. On Alpine
(musl) or Windows there is no bundled engine: new Nika() throws
NikaEngineUnavailable, so point bin or NIKA_BIN at a compatible engine,
or connect to a nika serve.
1
Install the package
nika <version> (<build>): the bundled engine, at the package’s version,
the engine your code will drive.2
Let the engine seal your runs (once per machine)
~/.nika/keys/ (mode 0600). That
is where the engine your app starts and nika serve read it, on macOS and
on Linux: neither opens an OS keychain. With it, the engine signs each
run’s record and traceVerify(receipt) answers verified. Skip it and
runs still succeed, unsigned. Keep NIKA_KEYCHAIN=off: without it,
nika key init refuses on a Linux terminal (its --force puts the key in
the desktop’s Secret Service, where neither looks) and on a Mac whose
keychain holds a key from Nika 0.122 or older, which 0.124.3 can neither
read nor copy. In CI, point NIKA_RUN_KEY_FILE and NIKA_RUN_PUB_FILE at
a key pair you provide.3
Save a workflow
Create
hello.nika in the application directory:hello.nika
mock/echo is the engine’s rehearsal model: it echoes the prompt back,
prefixed mock(echo) ·, with no key and no model call. permits: {}
grants the workflow no file, network, command or tool access.4
Run it from TypeScript
Save Node.js 22.18 or newer runs the
demo.mts next to the workflow:demo.mts
.mts file as is. On an older 22.x, name
it demo.mjs and drop <{ greeting: string }>.hello.nika and run again: the echo follows the
file.
Seeing
not verified: receipt_mismatch? The run succeeded, but the
engine found no run-signing key in ~/.nika/keys/, so the record is
unsealed. Do step 2, then run the demo again. On Linux, a key that
nika key init --force put in the Secret Service can be copied there
instead, from a terminal: ./node_modules/.bin/nika key align.What maxCostUsd: 0 does
maxCostUsd caps what this run may spend on metered models, at the catalog’s
list prices. Before anything runs, a cost floor above the cap makes run()
throw NikaOperationError with code NIKA-1709, and a cloud model the
catalog cannot price makes it throw with code run_refused
(price unknown: …): nothing is called and nothing is spent. During a run,
the call that crosses the cap completes and counts, nothing new starts, and the
result is failed with NIKA-1704. Local and mock/echo models are never
blocked. When you switch model: to a paid cloud model, raise maxCostUsd to
the budget you accept. Spend caps has the details.
Watch the events, after or during the run
A run keeps its events, so you can read them after the result:engine.event
carries the engine’s own workflow_completed frame on event.raw. Iterate
run.events() before awaiting run.result() to watch them live instead.
Run events explains the vocabulary and why a server run
yields fewer.
Audit without running
run() already checks the file, so you never need check() first. Use it to
show the audit on its own, in CI or an editor:
Pass your app’s data
inputs fills the workflow’s declared inputs: with literal JSON values:
'2' for an
integer input is refused with NikaOperationError (input_type_mismatch), an
undeclared key with unknown_input, and a missing required input with
NIKA-1708. Values stay literal: '@env:HOME' is the text @env:HOME, never
an environment lookup. Keep secrets out of inputs.
What a verified receipt proves
traceVerify(receipt) reads the record the run already wrote. It does not
re-execute the workflow or re-ask a model.
A record is tamper-evident, not tamper-proof: verification shows it is intact
and matches the receipt. Receipts covers both doors.
Next
Which version is this?
Which version is this?
How the SDK works
The two doors, the lifecycle and who owns what.
Project setup
Organize workflows, project policy and runtime state.
Run and cancel
Observe, settle and stop a run.
Server quickstart
The same methods against your own nika serve.