Skip to main content
Three surfaces sound like servers but accept different clients.
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.

Released OpenAPI routes (0.124.3, default server)

The contract has no POST /v1/run, job-list, schedule-list, schedule-delete, trigger or backfill routes, and no artifact upload or deletion. GET /v1/jobs/{id}/trace/verify answers in the CLI’s words, lower case: ok (intact, but unsigned or sealed with a key the server does not weigh: reason reads unsealed or unattributable), sealed, anchored and replayed hold; incomplete, tampered and broken do not; unavailable means the server holds no journal for that job. Both artifact routes answer only for a settled job whose journal verifies sealed: Outputs and artifacts covers the client side, and the server runbook what the door exposes.
Useful flags beyond these three: --state-root <dir> (job state, default .nika/serve), --run-cost-ceiling <USD|none> (per-job spend cap, default 1 USD), --allow-remote (acknowledge a non-loopback --bind; TLS belongs to a reverse proxy) and --authoring-model <provider/name> (seat provider authoring for POST /v1/compile). nika serve --help lists every flag. The standalone engine also supports operator standing cost rules: --cost-policy <RULE> admits bounded runs on a named unpriced API route without one-time cost review (costStandingPolicyV1). It does not enable --cost-review, change the server’s USD ceiling or authorize other tools. Read the running server’s capabilities and OpenAPI document before using an optional surface; the npm package can bundle an older engine.

Ask what a route offers

A workflow file can declare how its model calls travel: run.access (via, protocol, fallback, service_tier) and run.reasoning.effort. A run learns what its session offers on the way to its prompt, and says so only when it refuses. From engine 0.124.3 a server can be asked first:
  • The route is the file’s. The call names a served workflow and nothing else. The server asks only when the file declares run.access.via under run.access.protocol: acp; any other workflow answers status: 'not_applicable' with the reason, and no session is opened.
  • No prompt is sent. The server opens each session as a run opens it, selects the file’s model for that session only, lists what the session has for that model and ends it. prompts_sent is always 0.
  • One row per session shape and model. completion is the route’s one-shot profile, which infer: tasks run under; agent is its agent session, which agent: tasks run in. tasks names the tasks of each row.
  • effort.offered is exact. It holds the values a run accepts on run.reasoning.effort for that model. effort.current is what a run that declares no effort keeps on a session like this one. service_tier.offered holds the language’s words, standard and fast.
  • A model the session does not list is a state, not an error. model.status is then not_offered, with the models it does list in model.offered, and the efforts and tiers are unobserved.
  • A session that gives no offer is a row. status: 'unavailable' carries the code a run would meet before its prompt (NIKA-1803, NIKA-1804 or NIKA-1805) and a reason.
  • A row has a time. observed_at and fresh_until say when it was read and until when the server serves it again: 60 seconds, 15 when unavailable. One reading runs at a time on the server, and a ninth concurrent request is refused with NikaOperationError (access_offer_busy).
The call has its own deadline, 100 seconds by default (timeoutMs), because a first reading opens a session per row, and signal stops it. It needs a server that lists accessSessionOffer: on another server, and on the local engine, it rejects with NikaCompatibilityError before any request. An offer authorizes nothing. A model, an effort or a tier can leave a route between the offer and the run: run() is admitted as before, and the run selects, reads back and refuses on its own session. Harness access shows the document the server answers.

Local application path

This path needs no resident server. These examples target the published @nika-open/nika@0.124.5 npm package (bundled engine 0.124.5). The standalone engine CLI releases independently.

Local model path

nika model serve loads only models it has pulled (or a .gguf path), of the Qwen3 family in 0.124.3, and serves them on 127.0.0.1:8712. A workflow reaches it as a local provider: export NIKA_LLAMACPP_BASE_URL=http://127.0.0.1:8712 and use model: llamacpp/<model id>, as the banner prints. Application code does not submit workflow jobs to it.

Resident server

Operate the default firer and opt-in HTTP door.

Remote client

Configure the matching SDK transport.

Local models

Run inference on your own machine.

Deployment topologies

Choose a boundary by the job it owns.