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
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
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.