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 pinned OpenAPI includes jobs, job SSE, cancellation,
trace diagnostics, workflow discovery and schedule read/write. Artifact routes,
job listing and POST /v1/run are absent. --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.
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.
--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. 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.