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.nika serve with no --bind is the released resident firer. It reads the
arm: registry from nika.yaml, waits on the wall clock and ends each due
beat at the same firing law as nika arm fire. That default process is not
HTTP.
--bind + --workflows + --token-file on the same verb opens
authenticated HTTP. The released OpenAPI includes jobs, job SSE, cancellation,
trace verification, the download of a settled job’s artifacts, workflow
discovery and schedule read/write. It has no job-list or POST /v1/run route.
--once and --dry cannot bind a listener.
Rehearse each operating mode
--dry is intentionally narrower than a real fire. It does not take the beat
lock or apply the complete missed-run, overlap, cost and execution policy. Use
nika arm to see upcoming slots.
Reload without losing the last good registry
HOT RELOAD · INVALID EDITS DO NOT REPLACE VALID POLICY
The server retries a refused edit on a later tick. This keeps a typo visible
without silently replacing valid policy with an empty schedule.
Read process and beat outcomes separately
Each beat prints one decision line and appends project state. A completed--once sweep exits clean even when an individual workflow failed or paused,
so supervision must read the beat lines and ledgers, not only the outer process
exit.
Delivery and shutdown
Ctrl-C and SIGTERM stop the resident loop at its signal boundaries. The ledger uses durable claims and receipts, which yields at-least-once delivery:Opt-in HTTP
nika serve · listening http://127.0.0.1:18765 · GET /health and goes on to
list the authenticated routes.
--workflows <dir> scopes the served registry (0.118): the listing, the
metadata route and the schedules see only the workflows under that directory,
named from the project root (flows/quick.nika, never quick); a
schedule naming a workflow outside it is refused with the teaching. Executed
HTTP workflows use the runtime journal under the project’s .nika/traces/.
The runtime writes and seals the evidence; nika trace verify checks what
was written. A refusal before execution can have no journal, and missing or
incomplete evidence is distinct from a failed run. The artifact routes serve
only from a sealed journal: give the resident a run key as files first
(Server runbook).
A cancellation request is an action: the runtime’s eventual settlement, not
the HTTP request alone, determines the result.
POST /v1/jobs and POST /v1/check take two forms (0.118):
{"workflow": "<name>"} for a workflow the served registry lists — the
resident captures the world itself, exactly as a schedule fires — and the
execution snapshot nika check <file> --json --sdk-snapshot prints, whose
digests are optional caller-supplied integrity digests (absent, the resident
computes them; present, they must match the bytes). A retry with the same
Idempotency-Key finds its job before the registry is read again. The
terminal event (execution.settled · execution.cancelled) carries the
run’s settlement whole (status · cause · elapsed_ms · tasks ·
spend · error), the same object run_settled flattens; nika doctor
says which resident runs (the stores’ writer stamp beside the server lease);
nika explain <code> teaches every resident code.
The route table lives at GET /v1/openapi.json. Full matrix:
server surfaces.
Deployment checklist
- Set a stable project
cwdcontainingnika.yaml. - Install an explicit
nikabinary path. - Protect provider keys outside project source.
- Persist
.nika/traces/and.nika/arm/according to policy. - Capture stdout decision lines.
- Send SIGTERM and allow the active firing boundary to settle.
Continue
Arm registry
The schedule and policy this process consumes.
OS schedulers
Let launchd or systemd own wakeups instead.
Runtime state
Persist the evidence behind each decision line.
Production runbook
Boot, supervise, probe and investigate the process.
Deployment topologies
Choose the right process boundary.