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 is a foreground process for one project. A production runbook
should name its room, binary, state volume, signal path and evidence checks.
Boot gate
Run every probe from the working directory production will use:nika arm lists the beats and their next slots;
serve --dry --once prints what would fire now and exits (without --once,
--dry stays resident). Neither exercises provider credentials or external
effects.
Supervise the foreground process
The minimal systemd service contract is ordinary:WorkingDirectory and ExecStart. Provider keys stay in the protected
environment file. The project source and .nika/ volume need only the access
the workflows and evidence policy require.
For unattended jobs on an API route the catalog cannot price, configure
standing cost rules in the service’s
startup command. Keep the project .nika/ durable: its admission-window
ledger is separate from --state-root. A rule bounds requests and run
frequency; a USD ceiling still needs a known or operator-declared price.
Units emitted by
nika arm --emit systemd are per-beat timer bridges. They
are not the service unit for the resident nika serve loop.Probe the surfaces that exist
Barenika serve does not listen on an HTTP port — the firer loop has no
socket, so an HTTP health probe there would be a fictional contract. With
--bind the same verb does listen: probe GET /health on the bound
address instead.
SERVER PROBES · EACH ANSWERS ONE QUESTION
Treat process liveness and workload success separately. A resident loop can be
healthy while one workflow fails, and a completed --once sweep can exit zero
after an individual beat failed or paused.
Artifact downloads
With--bind, the server also serves what a settled job produced, and
/health lists artifacts. GET /v1/jobs/{id}/artifacts lists the files the
job’s sealed journal records (saved inside the project by nika:chart,
nika:image_generate, nika:tts_generate, nika:image_fx or
nika:image_compose, the images an agent’s harness sent, and the files an
agent: task saved from them), and GET /v1/jobs/{id}/artifacts/{name} streams
one. Decide what that door exposes before you open it:
- Who can read what. Any caller holding the token and a job’s id can
download those files from any settled job the state root holds. The server
opens a file at its recorded place below the project root and refuses a
symbolic link at any component. It lists no file under the project’s
.nika(an agent image is served from its blob there), and no file the journal records without a digest (whatnika:writeandnika:editwrote). A request names a manifest entry, never a path. - Sealed journals only. The routes judge the job’s journal with the
verifier
nika trace verifyruns, and serve nothing unless it is sealed, intact and headed by the job’s receipt (409 artifact_journal_unverified). A server without a run key still listsartifactsand answers that409for every job. - Bounds. One artifact is served up to 256 MiB; a larger one stays listed
and its download answers
403 artifact_too_large. A manifest lists at most 1,024 entries. At most four journal verifications or pre-download hash passes run at once (503 artifact_capacity). A download is not bounded by the request deadline; the connection limit bounds streams. - Retention. The routes add no store and delete nothing. A job stays
downloadable while its journal and its files stay as recorded: a file
changed since the run answers
409 artifact_changed, and the server never serves other bytes in its place. - Re-serving. The bytes come with
Content-Disposition: attachment,X-Content-Type-Options: nosniff,Content-Security-Policy: sandboxandCache-Control: no-store. Keep them when a proxy or your application serves the file again: an SVG can carry script.
Give the server a run key
Mint the key as files, as the user the server runs as, before the jobs you want to download from:~/.nika/keys/. To keep it elsewhere, name both files, for
nika key init and then for nika serve (in a unit, put both variables in
its EnvironmentFile):
~/.nika/keys/run-signing.pub,
then the retired-key ledger. GET /v1/jobs/{id}/trace/verify then reads
sealed and the artifact routes serve the job. nika trace verify run with
the same two variables set attributes those journals without --key.
Deploy a project change
1
Stage the exact bytes
Put the candidate
nika.yaml and workflows in the release directory that
will become the production project room.2
Preflight there
Run
nika arm --plain with the pinned binary. A clean report validates the
project file and its cadences without scheduling work.3
Switch deliberately
Replace the project release or edit the registry. The resident loop swaps
only a valid registry and keeps the last good one after a refused edit.
4
Read the next decision
Confirm the process remains live and inspect the next beat line plus its
sidecar evidence. Hot reload success is not the same as workflow success.
Investigate one surprising beat
Follow one path instead of searching every log at once:Production checklist
- One explicit project
cwd. - One pinned binary path and printed version.
- A
nika.yamlwhose beats all readREADYinnika arm --json. - Provider secrets outside source and generated units.
- Durable
project/.nika/storage with chosen retention and access. - A run key as files (
~/.nika/keys/or the explicit pair) when runs must verify sealed or an HTTP door serves artifacts. - Captured stdout decision lines and stderr diagnostics.
- SIGTERM delivery with enough time for the active firing boundary to settle.
- An incident path from decision to ledger to verified trace.
Continue
Resident server
Read reload, shutdown and delivery semantics.
CWD and monorepos
Align project discovery and state roots.
Runtime state
Place ledgers, watermarks and traces.
Security boundary
Keep permits, secrets and spend explicit.