> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Security boundary

> Preserve argv safety, default-deny permits, secret names, spend ceilings and caller cancellation.

The SDK carries types and transport. The engine remains the policy enforcer.

## Local seam

> [!TIP]
>
> **One client, local by default.** Import `Nika` from
> the package root and omit `url`. The client takes the engine
> from `bin`, then `NIKA_BIN` (both absolute paths), then
> the platform package npm installed with it; it never uses a
> `nika` found on your `PATH`. These examples target
> the published [0.124.4 SDK release](https://github.com/supernovae-st/nika-client/tree/v0.124.4).

PROCESS BOUNDARY · ONE ARGV VALUE

<pre tabIndex="0">
  unsafe  shell("nika run " + path)

  &#x20;   safe    spawn("/abs/path/to/nika", \["run", path, "--json"])
  &#x20;                                         └── never shell-parsed
</pre>

The local transport spawns the resolved absolute engine path with an argv
array and never wraps a workflow path in a shell string. A bare `nika` would
make the operating system search `PATH`, so `bin` and `NIKA_BIN` must be
absolute.

## Admit authority before execution

```ts theme={"system"}
const reviewedPrograms = new Set(['git', 'ls']) // your policy, reviewed
const secretsAllowedHere = false

const report = await nika.check(file)
if (!report.clean) throw new Error('workflow is not admitted here')

// Narrow the engine-owned fields your policy reads; the SDK types them as unknown.
const permits = report.permits as { declared?: { exec?: string[] } }
const cost = report.cost as { bounded_total_usd?: number; has_unbounded?: boolean }
const requirements = report.requirements as { secrets?: unknown[] }

if ((permits.declared?.exec ?? []).some((program) => !reviewedPrograms.has(program))) {
  throw new Error('an unreviewed program is permitted')
}
if (cost.has_unbounded || (cost.bounded_total_usd ?? 0) > 0.25) {
  throw new Error('the cost ceiling is above this route\'s budget')
}
if ((requirements.secrets ?? []).length > 0 && !secretsAllowedHere) {
  throw new Error('this route does not hand out secrets')
}

const run = await nika.run(file, {
  maxCostUsd: 0.25,
})

// Wire cancellation defensively: an already-aborted signal never fires
// 'abort' again, and a rejected cancel promise must not go unhandled.
if (request.signal.aborted) {
  void run.cancel().catch(() => {})
} else {
  request.signal.addEventListener(
    'abort',
    () => { void run.cancel().catch(() => {}) },
    { once: true },
  )
}
const result = await run.result()
```

A `check()` report describes the bytes it read at that moment; `run()`
re-admits the file's current content. If the path is mutable between the
two calls, the report does not authorize what actually executes — gate the
path's integrity, or snapshot first.

Check these facts explicitly:

* permitted filesystem paths, network hosts, programs and tools;
* model and environment requirements;
* secret names, never values;
* the static cost floor and unbounded flag;
* explicit `run.cancel()` and runtime ceiling.

## Remote seam

> [!NOTE]
>
> **The same client selects HTTP when `url` and
> `token` are present.** A served name such as
> `workflows/release.nika` (its path from the project root) goes
> directly to the server and needs no local engine or file. An explicit local
> path such as `./release.nika` needs a compatible local engine to
> capture an immutable snapshot. The released OpenAPI of
> `nika serve` 0.124.4 covers jobs, SSE events,
> cancellation, trace verification, the artifacts a settled job's sealed
> journal records (behind `run.artifacts()`), workflow listing,
> schedule read and write, stateless authoring
> (`POST /v1/compile`, behind `compile()`) and what a
> workflow's declared ACP route offers (behind `accessOffer()`). It has no
> `POST /v1/run`, job-list, or schedule list, delete, trigger
> or backfill route. The server owns its engine version; check its
> compatibility separately from the bundled local engine.

Bearer tokens belong in governed environment or workload identity plumbing,
not source. The SDK exposes no logger or webhook verifier; keep application
logging and delivery secrets outside the Nika transport.

The token also downloads artifacts: any holder who knows a settled job's id
can read the files that job's sealed journal records, the project files a
builtin saved, the images an agent's harness sent and the files an `agent:`
task saved from them. The server serves only
bytes that still match the journal, and the SDK checks them again on arrival,
but the content is still whatever the workflow produced. Treat a downloaded
file as untrusted input, and keep the server's
`Content-Security-Policy: sandbox`, `nosniff` and `attachment` headers if your
application serves it again.
[Server runbook](https://docs.nika.sh/sdk/operations/server-runbook.md#artifact-downloads) lists what
the routes expose.

## Threat boundaries

| Boundary | Owner |
| - | - |
| Workflow grammar and permits | Engine |
| Process argv and cancellation verb | SDK |
| HTTP admission timeout and bounded event views | SDK |
| Secret storage and identity | Deployment |
| Artifact download: settled jobs, sealed journal, recorded bytes only | Engine (`nika serve`) |
| Artifact bytes re-checked on arrival | SDK |
| Run-signing key custody on the server | Deployment |
| Artifact destination and retention after download | Application |

## Continue

> [card] [Security concepts](https://docs.nika.sh/concepts/security.md)
>
> Read the default-deny engine model.

> [card] [Cost honesty](https://docs.nika.sh/guides/cost-honesty.md)
>
> Refuse unknown spend deliberately.

> [card] [Webhooks](https://docs.nika.sh/sdk/remote/webhooks.md)
>
> Verify delivery before dispatch.

> [card] [CI gate](https://docs.nika.sh/sdk/operations/ci.md)
>
> Put admission before secrets.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.