Skip to main content

Shared bounds

machineBufferBytes bounds what the SDK holds of one machine frame (a local engine’s stdout line, a server’s SSE event), one JSON document a server answers, one captured engine report, and the engine diagnostics a result keeps. Its default, 16 MiB, is the bound of a nika serve job store, which refuses rather than truncates a result that would outgrow it: every result a server settles reaches run.result() and attachRun() under the default. A local engine bounds no frame, so a local result above 16 MiB needs a larger value. Past the bound the SDK rejects with a NikaProtocolError that names the option and the size to set; on a server the job keeps its result, and a client with a larger bound reads it again with attachRun(). Artifact downloads are not bounded by it.

Local by default

Engine resolution is bin, then NIKA_BIN, then the platform package npm installed with the SDK. bin and NIKA_BIN must be absolute paths: a bare name or a relative path throws NikaConfigurationError. A nika on your PATH is never used.

Remote when a URL is present

For an explicit local path, cwd and bin select the compatible local engine that captures its immutable snapshot. Contained served names go directly to the resident and do not require either local source or a binary.

Operation options

inputs is the application channel. Values are strict JSON and stay literal — a string is never read as @env:NAME, an expression or a number, and nothing is coerced to the declared type. The engine validates the map (unknown key, type mismatch, missing required input) and refuses before any run exists; a value JSON cannot carry rejects run() with NikaConfigurationError instead of being dropped. The channel needs an engine that advertises it — inputsLiteral natively (values ride stdin, never argv), jobInputs over HTTP by served name — and an engine without it rejects with NikaCompatibilityError; the SDK never falls back to --var. An execution snapshot freezes its inputs, so an HTTP run of an explicit local path refuses inputs. Never put a secret here. vars is deprecated: the native --var KEY=VALUE operator channel — the engine reads @env:NAME from its own environment and coerces text to the declared type, so it cannot carry literal API values and has no HTTP form. Combining vars with inputs rejects run().

Access pins

model: picks the intelligence; access picks the path the engine takes to it, the value nika run --access and nika check --access take: an access class (local, mock, harness, oauth, api) or a harness seat (claude-code, codex, copilot, gemini-cli, grok-build, kimi-code, opencode, qwen-code). NikaAccessPin lists those words for completion and takes any string: the engine judges a pin and never substitutes another path or model.
The SDK itself refuses only a value neither door can carry unchanged, before anything starts: a non-string, a NUL byte or a lone surrogate (NikaConfigurationError). Over HTTP the pin is part of the request bytes an idempotency key binds: retry with the same pin. Remote check refuses model and nativeStrict. Remote run requires idempotencyKey (reuse the same key and request after an uncertain response), takes access with a served name, and refuses vars, model and maxCostUsd with NikaCompatibilityError; the server applies its own spending ceiling (Spend caps). Signals stop a request or observer; only run.cancel() requests cancellation of admitted work; run.result() carries the actual outcome.

Method index

See where each option is consumed.

Type index

Read the exported projections.