Skip to main content
Supplying url selects HTTP. There is no environment-reading constructor: read and validate deployment configuration in your application. New to nika serve? Start with the server quickstart.

Served names and local snapshots

A served name selects a workflow the server serves. It is the workflow’s path from the server’s project root (the folder holding nika.yaml), not from --workflows: a server started with --workflows ./workflows serves workflows/release.nika, and the short release.nika answers not_found (404). await nika.listWorkflows() returns the exact names. check() and run() send the name directly; no local engine or file is needed. To submit local source instead, pass an explicit path such as ./flows/release.nika or an absolute path. The SDK then resolves a compatible local engine from bin, NIKA_BIN or the platform package, captures an immutable snapshot relative to cwd, and sends its exact bytes. It never falls back from an unserved name to a local file. A snapshot freezes its inputs, so a local path refuses inputs.

Connection rules

Plain HTTP is accepted only to a loopback host (localhost, 127.0.0.0/8, [::1]), and only with allowInsecureHttp: true: even with the flag, a plain-HTTP URL to another host is refused. Every other host needs HTTPS, so the token never leaves the machine in plaintext. URLs cannot carry credentials, queries or fragments; bearer tokens must be 32–512 visible ASCII bytes.
requestTimeout bounds HTTP admission. fetch, eventBufferSize and machineBufferBytes are the other transport seams. machineBufferBytes bounds one SSE frame or JSON document; its 16 MiB default is the server’s own job-store bound, so it holds every result the server settles. Neither bounds an artifact download. The SDK does not expose automatic retry or concurrency policy as constructor options.

Check a served name

A successful served-name check returns clean: true with the resident’s compact acknowledgement: status: "accepted", snapshot_digest, root and units. A missing served name or a workflow admission refusal returns clean: false with the typed resident error (code, optional message). This is not a local findings report: it has no local process exitCode and does not invent findings. Authentication, transport and protocol failures still throw. An explicit local-path check retains the local engine’s full check report; when capture succeeds, the resident must acknowledge that exact snapshot before the SDK returns it. Remote checks reject model and nativeStrict overrides because the HTTP request has no envelope for them. access rides a served name (CheckByName.access): the server’s check is source-only and evaluates no access plan, so it acknowledges any pin that is not empty or blank.

Jobs

Admit, recover, observe and cancel durable jobs.

Configuration

Read the exact local and remote unions.