Skip to main content
Five minutes from zero to a typed workflow result inside your own app: install the package, save one file, run it, read the outputs, verify the record. You need Node.js 22 or newer on macOS (arm64, x64) or Linux with glibc (x64, arm64). No server, no global CLI and no provider key: this example runs on the engine the package bundles, with the 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

npm brings the engine for your platform as an optional dependency: keep optional dependencies enabled. The second line prints 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)

This writes a run-signing key pair to ~/.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 demo.mts next to the workflow:
demo.mts
Node.js 22.18 or newer runs the .mts file as is. On an older 22.x, name it demo.mjs and drop <{ greeting: string }>.
That is the whole loop: one file, one call, one typed result, one verified record. Change the prompt in 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:
Six events for this one-task workflow on the local engine; 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:
The engine type-checks them before any run exists: a string '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

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.