Server quickstart

printf 'nika: my-project\n' > nika.yaml
mkdir -p workflows

nika: hello
model: mock/echo
permits: {}
tasks:
  greeting:
    infer:
      prompt: "Say hello from the Nika SDK."
      max_tokens: 32
outputs:
  greeting: ${{ tasks.greeting.output }}

mkdir -p .nika
umask 077 && openssl rand -hex 24 > .nika/serve.token && chmod 600 .nika/serve.token

./node_modules/.bin/nika serve \
  --bind 127.0.0.1:8787 \
  --workflows ./workflows \
  --token-file .nika/serve.token

import { readFile } from 'node:fs/promises'
import { Nika, isNikaRunSucceeded } from '@supernovae-st/nika'

const token = (await readFile('.nika/serve.token', 'utf8')).trim()
const nika = new Nika({
  url: 'http://127.0.0.1:8787',
  token,
  allowInsecureHttp: true, // plain HTTP, accepted only to a loopback host
})

console.log(await nika.listWorkflows()) // [ 'workflows/hello.nika' ]

// A served name is the workflow's path from the project root.
const run = await nika.run<{ greeting: string }>('workflows/hello.nika', {
  idempotencyKey: `hello-${Date.now()}`, // store it before the call; reuse it on retry
})
for await (const event of run.events()) console.log(event.sequence, event.kind, event.status)

const result = await run.result()
if (!isNikaRunSucceeded(result) || !result.receipt) throw new Error(`job ended ${result.status}`)
console.log(run.id, result.outputs?.greeting)

const proof = await nika.traceVerify(result.receipt)
console.log(proof.verified, proof.verdict, proof.reason)

node remote.mts

[ 'workflows/hello.nika' ]
1 run.started running
2 run.settled succeeded
277e5b29-301a-4366-b1a5-00d89a93d14e mock(echo) · Say hello from the Nika SDK.
true ok unsealed

​

What changes from the local engine

• Workflows by served name. workflows/hello.nika is the workflow’s path from the project root (the folder that holds nika.yaml), whatever --workflows says. A short name such as hello.nika answers not_found (404). listWorkflows() returns the exact names.
• An idempotency key per job. run() over HTTP requires one. Retry a request whose response was lost with the same key and you get the same job, not a second one.
• Two events, not six. The server streams run.started and the settlement, with an event.sequence cursor, and no per-task events.
• No per-run maxCostUsd or model. The server caps every job at 1 USD by default (--run-cost-ceiling); see Spend caps.

The same client against nika serve, set up as the SDK README on GitHub does it. Unlike the steps above, hello.nika stays at the project root, so the server starts with --workflows . and serves it as hello.nika; the server runs in the background of the same terminal; and NIKA_KEYCHAIN=off nika key init gives it a signing key, so the verdict is sealed, not ok. /health reports engine 0.123.0 and machine protocol 2. The client, built with new Nika({ url, token, allowInsecureHttp: true }), lists and checks the served workflow, runs it with an idempotency key, receives the two sequenced events, reads verified · sealed, gets the same job back when it retries with the same key, and a typed 401 for a wrong token. The token is never printed. Recorded in a terminal from @supernovae-st/nika 0.123.0 and nika serve 0.123.0 on loopback; the run is a mock/echo rehearsal, with no provider key.

$ test -f nika.yaml || printf 'nika: my-project\n' > nika.yaml
$ mkdir -p .nika && (umask 077 && openssl rand -hex 24 > .nika/serve.token)
$ printf '.nika/\n' >> .gitignore        # traces, job state and the token stay out of git
$ NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init   # the server signs each job's record
run-signing key minted · fingerprint 9d7d19293f10bb9a
  every run on this machine now seals its journal (verify: nika trace verify <file>)
$ ./node_modules/.bin/nika serve --bind 127.0.0.1:8787 --workflows . --token-file .nika/serve.token > serve.log
2>&1 &
[1] 77688
$ curl -s 127.0.0.1:8787/health | jq -c '{engineVersion, machineProtocolVersion}'
{"engineVersion":"0.123.0","machineProtocolVersion":2}
$

── screen cleared ──

$ node remote.mts
served   hello.nika
check    clean
job      67da7ec9-eba2-4a2f-ad8c-62faab9166d5
  #1 run.started running
  #2 run.settled succeeded
result   succeeded · mock(echo) · Say hello from the Nika SDK.
verify   verified · sealed (the server's verdict on its own journal)
retry    the same job: it did not run twice
bad token 401 unauthorized
$ kill %1
$
[1]  + done       ./node_modules/.bin/nika serve --bind 127.0.0.1:8787 --workflows .   >  2>&1
$

​

Serve other machines