---
slug: the-server-door-opens-on-loopback
title: "The server door opens on loopback"
tag: Engine|Security
date: 2026-08-23
published: 2026-11-17
receipts:
  - https://github.com/supernovae-st/nika/commit/bb9bda7d1f9dc7a846d2192749a149c0299ec54c
  - https://github.com/supernovae-st/nika/commit/b39c1853e04fa0be97494e4c8ab3749b66490c7e
  - https://github.com/supernovae-st/nika/commit/f6654d03e14483318c106a72323bde505c845cb6
  - https://github.com/supernovae-st/nika/commit/dc5391adf02fce46e42b30b528f06942e8f03679
  - https://github.com/supernovae-st/nika/commit/46e7ae5509e971913a765f7043c307f8076a7de1
  - https://github.com/supernovae-st/nika/commit/8c29caa2c56cccadcffb5f03b1abfd54e5b24dc5
description: "In v0.114.0, nika serve began taking jobs over HTTP: bound to loopback, with a token read from a file, running the bytes it accepted."
---

Before v0.114.0, `nika serve` had one job. It was the resident that fires schedules: a project declares its beats under `arm:` in its `nika.yaml`, and the resident starts each workflow when its time comes. ADR-117 describes it in two short sentences: "The shipped `nika serve` is a local resident ARM firer. It opens no listener."

Nika v0.114.0, released on 23 August 2026, gave the resident a second mode. Its notes call it "Remote execution as a loopback door". With three flags, the same process accepts jobs over HTTP, streams their events and publishes its own list of routes.

A workflow engine that grows an HTTP API usually grows an attack surface with it. What makes this release worth reading is how little the door admits, and how much of that was settled before the first route existed.

## The decision came first

Two days before the release, on 21 August, the project recorded the boundary as an architecture decision, ADR-117, together with a threat model. An architecture decision record is a short document that states a choice, its reasons and what it rules out.

ADR-117 sets an order: "No HTTP route may land before those first two authorities are usable by both CLI and Serve." The two authorities it names are the schedule library and a shared execution service that performs "check + composition once". In plain words, the command line and the server had to share that code before any route was added, and the server part "does not import `nika-cli`" or "reimplement check/run composition". The record gives the reason in its context section: "Exposing routes first would make transport invent authority the runtime does not possess."

The same record lists the shortcuts it refused. One is "Trust loopback and omit authentication". It was rejected because "Browsers, compromised local processes, port forwards, and containers cross the loopback boundary." The threat model says it in one sentence: "Loopback is not a trust boundary."

That is why the door listens on 127.0.0.1 and still asks for a token.

## Three flags open it

Bare `nika serve` still opens no socket. HTTP needs three flags together:

- `--bind` names the address. The listen line "prints the bound address, including port 0", so an operator who asks the system for any free port learns which one it got.
- `--workflows` names one folder. Only workflows under it are served, and a request cannot name an absolute path or climb out of it.
- `--token-file` names the file that holds the bearer token. The notes give the reason in parentheses: "credential bytes never enter argv", the list of arguments a program is started with. The threat model applies the same rule to "structured logs, traces, errors, panic messages, OpenAPI examples, or health output".

The engine's operations guide shows the door as it works today. Its workflow is a rehearsal: the model `mock/echo` sends the prompt back, so it needs no key and no network.

```yaml hello.nika
nika: hello
model: mock/echo
permits: {}
tasks:
  greeting:
    infer:
      prompt: "Say hello from nika serve."
      max_tokens: 32
outputs:
  greeting: ${{ tasks.greeting.output }}
```

The guide writes that file under `workflows/` next to a one-line project file. Then it checks the workflow, creates a token only its owner can read, and starts the server:

```sh
nika check workflows/hello.nika
umask 077
mkdir -p .nika/serve
openssl rand -hex 24 > .nika/serve.token
chmod 600 .nika/serve.token
nika serve --bind 127.0.0.1:8787 --workflows ./workflows --token-file .nika/serve.token
```

From a second terminal, it checks that the server answers, then starts a job:

```sh
curl -s http://127.0.0.1:8787/health
curl -s -X POST http://127.0.0.1:8787/v1/jobs \
  -H "Authorization: Bearer $(cat .nika/serve.token)" \
  -H 'Idempotency-Key: first-run' \
  -H 'Content-Type: application/json' \
  -d '{"workflow":"workflows/hello.nika"}'
```

The guide states the rules: "`/health` needs no token", every other route needs the bearer token, and `POST /v1/jobs` also needs an `Idempotency-Key`. "A new job answers `202` with its id and `"status":"queued"`."

This is today's form, from the guide as it reads in v0.124.4. Two details came later than 0.114.0: workflow files end in `.nika` since v0.120.0, and the job body that names a workflow by its served name is recorded in the changelog under 0.118.0, a tag with no public release, so it first shipped publicly in v0.118.6. The door, its flags and its token rules opened in v0.114.0.

## What the door refuses to do

Four choices in 0.114.0 keep the door narrow.

**It runs what it accepted.** The notes say: "The worker runs the POST-time snapshot, not live files." When a job is accepted, the server captures the workflow's bytes at that moment. A fix in the same release adds: "A symlink or rewrite after 202 cannot run bytes the client never admitted."

**Every effect carries a key.** ADR-117 requires a bounded `Idempotency-Key` on every POST that can cause an effect, and binds it to the request: "an identical replay returns the existing job, while a key reused with different bytes refuses." A client that loses a response and sends the request again gets the same job, not a second run.

**It publishes only routes that exist.** `GET /v1/openapi.json` returns an OpenAPI 3.1 document built from the live route table. Job events stream as server-sent events at `GET /v1/jobs/{id}/events`, and the notes say each frame carries `{sequence,kind,status}` only. Routes with no authority behind them stayed out: "Cancel, artifacts and `/v1/run` stay 404", and the OpenAPI document omits them. ADR-117 explains why they waited: "A 202 response without runtime settlement authority and a path string without artifact custody would be a false contract."

**It checks credentials before it parses the request.** The decision puts authentication and a coarse size check before any JSON parsing, workflow lookup or job lookup. A missing, duplicated, malformed or wrong credential gets the same bounded 401. Comparison is constant-time, and only `GET /health` is public.

## The doctor looks at the token file

`nika doctor`, the command that reports what a machine can do, learned about the door in the same release. When `.nika/serve.token` exists, it checks the file's mode. Owner-only passes. A file that the group or other users can read fails, and the fix it prints is the `umask 077` line. Without a token file the row stays silent, because the door is opt-in. The notes add the point that matters for anyone putting this on a server: "The row never claims TLS", because "that is the reverse proxy." The release added a systemd unit and a Caddy file to `docs/ops/` for that setup.

Three days later, v0.115.0 made the server teach the same steps itself. A missing `--token-file`, a short secret or a file others can read now prints the `openssl` line instead of an opaque refusal, and the server never echoes the bytes.

## Why the order matters

An application that talks to this door can rely on three things from the first release. The notes call it "authenticated loopback HTTP", and a non-loopback bind needs an extra flag. Its token never sat on a command line. A job runs the bytes the server accepted, not whatever is on disk when the worker gets to it.

The order is visible in the history: the decision and the threat model on 21 August, then on 23 August the commit that adds "durable jobs and shared execution" and, after it, the one that admits loopback HTTP. The routes that could not yet be honest, cancel and artifacts, were left out; ADR-117 rejected shipping them "as best-effort route behavior".

## What this does not do

- **No TLS.** The server speaks plain HTTP. ADR-117 places remote use behind "an operator-controlled TLS reverse proxy or on a protected private network" and calls direct cleartext exposure to the public Internet "outside the supported boundary". A non-loopback bind needs `--allow-remote`, a flag that "only acknowledges exposure".
- **No cancel, no artifacts, no `/v1/run` in 0.114.0.** Cancel came in v0.116.0, whose notes say the server "supports idempotent cancellation and replay", and the download of a finished job's files in v0.123.2. `/v1/run` never arrived: the engine's own OpenAPI test still lists it among the absent paths.
- **One token, one authority.** ADR-117: "The initial API has no multi-tenant authorization model." One configured credential is "one authority domain", and tenancy "requires a later ADR". From v0.115.0, a non-loopback bind's listen line adds "that the blast radius is every workflow in `--workflows`".
- **The threat model names what it cannot stop.** It "does not claim protection from an attacker who can read the server's credential source or replace the running binary". As it reads today, it "equally does not claim protection from one who can write the durable job root".

Read the [v0.114.0 release](https://github.com/supernovae-st/nika/releases/tag/v0.114.0), the [operations guide](https://github.com/supernovae-st/nika/blob/main/docs/ops/README.md), [ADR-117](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-117-nika-serve-network-boundary.md) and the [threat model](https://github.com/supernovae-st/nika/blob/main/docs/security/nika-serve-threat-model.md), or continue with [The access layer is an operating contract](/blog/the-access-layer-is-an-operating-contract).
