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.
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:
This proves binary resolution, project discovery and cadence parsing before a resident process starts. 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:
Pin 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

Bare nika 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 (what nika:write and nika:edit wrote). A request names a manifest entry, never a path.
  • Sealed journals only. The routes judge the job’s journal with the verifier nika trace verify runs, 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 lists artifacts and answers that 409 for 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: sandbox and Cache-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:
The pair goes to ~/.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):
The server seals each job with that pair, and weighs the public keys in the order it signs: the pair’s public half, then ~/.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:
An unmatched claim is evidence of uncertainty after a crash. It is not proof that the external effect did or did not happen. Keep those effects idempotent and investigate the external system before replaying.

Production checklist

  • One explicit project cwd.
  • One pinned binary path and printed version.
  • A nika.yaml whose beats all read READY in nika 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.