Skip to main content
Live project control plane. The released engine discovers nika.yaml from the working directory toward its ancestors. The file is optional when built-in defaults are enough. Its project-shape grammar is closed: nika · ceiling · arm · traces · registry. Direct runs and the cadence path (nika arm · nika serve) read the same file.
The SDK should make the project boundary visible, not dissolve it into application objects. The root nika.yaml is the control plane — optional for a first workflow, required once the project arms beats or sets policy. Each *.nika file is executable workflow intent.
PROJECT TREE · CONTROL PLANE + INTENT + PROOF
  • nika.yaml governs project-wide spend and the released reader profile this project uses.
  • workflows/ is reviewed as intent.
  • src/nika.ts owns binary resolution and the working directory, not a second copy of project policy.
  • .nika/ is runtime state: run records, firing ledgers, server job state and, when you serve over HTTP, the server’s bearer token. Ignore it in source control and mount it deliberately on a server.

Found the project

A project file is one line: the project’s kebab-case name. Create it and let the engine read it back:
nika arm reads and validates the project file and its cadences, reports what is armed, and schedules nothing. Add policy as you need it, for example a default spending ceiling for every run of the project:
nika.yaml
nika init does much more than create nika.yaml: it writes about 30 agent, editor and hook files and a starter workflow (the full list). Run it only when you want that scaffold.
Add arm: when time or an event should start a workflow, and traces: or registry: for run policy: one file carries both. The project file and arm registry pages show copy-paste forms.

Create one client

fileURLToPath decodes percent-escapes and survives spaces in the path — new URL(...).pathname does neither. Binary resolution follows one ladder:
  1. bin passed to the constructor
  2. NIKA_BIN
  3. exact optional platform package
Use an explicit application variable for packaged services. bin and NIKA_BIN must be absolute paths: a bare name or a relative path throws NikaConfigurationError, and a nika on your PATH is never used. cwd anchors relative workflow paths, project-file discovery and the .nika/ state directory.

Probe at startup

A missing binary is an environment failure (the promise rejects). A dirty workflow is different: check() resolves to a report so the caller can show every finding — branch on report.clean, never log readiness while it is false.

Keep receipts governed

.gitignore
Everything under .nika/ is machine state:
Never commit .nika/serve.token: it is the bearer token that lets a client run workflows on your server.
If a deployment retains this state, choose the volume, retention window and access policy explicitly.

Connect the next systems

Security boundary

Keep permits, secrets, argv and spend ceilings explicit.

Local client

Read every local method and its machine twin.

Workflow concepts

The file remains the language contract.

Traces

Understand the durable journal under the SDK receipt.

Resident server

Keep armed beats running on a container, VM or bare server.

Runtime state

Persist traces and arming ledgers without committing them.