[Feature]: Third-party hosts driving nvpair-ui-broker: is the JSON-RPC surface a supported contract, is the app-data layout versioned, and can the proxy expose the serving node?

[nathaniel-magieva]

Area

nvpair-ui-broker (JSON-RPC surface, --ipc mode), nvpair-cluster-manager (app-data / cluster dir layout), ollama-proxy (response headers)

User problem

We are integrating PAIR as the LAN inference layer behind our own desktop application (Magieva Desktop, an Electron app; we are an NVIDIA Inception member). Our host process supervises nvpair-ui-broker itself — spawned with piped stdio, or over --ipc — instead of the shipped PAIR UI, and relies on:

• discovery:get-nodes / discovery:subscribe → discovery:nodes-changed for the roster (members, addresses, modelsByEngine, loadedByEngine, trusted / clustered);
• workloads:subscribe → workloads:upsert with workloadInfo.scheduledOn / originatedFrom to record which node actually served each request (we write it to our usage ledger);
• cluster:invite-node / cluster:respond-to-invite / cluster:invite-status and engine:remote-install / engine:remote-pull-model to drive pairing and model placement from our own UI;
• the per-user app-data directory (~/Library/Application Support/Nvidia Corporation/Personal AI Router on macOS) and the cluster dir (identity.json, node.crt, node.key, trusted/) so an existing NVIDIA-created node keeps its identity when our host takes over supervision.

Measured on v0.1.1 (13b6811, built from source with Go 1.25, macOS 26 / Apple M4 Max): all of the above works today when the broker is driven from a plain shell over newline-delimited JSON-RPC 2.0 — app:ready in ~3 s, the roster is pushed, a real Ollama turn through the proxy yields workloads:upsert with scheduledOn set, and the invite / engine methods are routed. What we cannot determine from the repo:

1. Is the broker's JSON-RPC method + notification surface a supported integration contract, with a compatibility policy across releases (additive changes only? deprecation window?), or is it considered internal to the shipped UI?
2. Is the on-disk format of the app-data and cluster directories versioned? node-id.json and cluster/identity.json carry only node_uuid and created_at; services/VERSIONING.md versions binaries, not the data layout. A third-party host cannot tell whether a directory written by a newer or older PAIR is safe to attach to, or refuse it cleanly.
3. Will the proxies expose the serving node on the HTTP response (e.g. an X-PAIR-Served-On: <hostUuid> header)? Today it is available only through the broker event stream (proxy:proxy/request.node_id, workloads:upsert.scheduledOn), which is fine for a host that also owns the broker, but not for an Ollama-compatible client that only sees the proxy.

Desired outcome

• A short statement in the broker README (or a docs/integration.mdx) of which methods/notifications are stable for third-party hosts and how breaking changes are announced.
• A format_version (or equivalent) field in node-id.json / cluster/identity.json, plus a documented rule for what a host should do when it does not match.
• Optionally, a X-PAIR-Served-On response header on ollama-proxy / lmstudio-proxy responses.

Alternatives considered

• Pinning to a vendored v0.1.1 build and treating every upgrade as a full re-validation of the JSON-RPC surface (what we will do if the surface is declared internal).
• Reading the serving node only from the broker events (works for us; leaves plain Ollama clients unable to attribute a response).
• Inferring the data-dir version from file shape (fragile; the reason for question 2).

Compatibility and security implications

Additive only: a version field and a response header change no existing behaviour. A published compatibility policy lets hosts fail closed on a surface they do not recognise instead of guessing. No change to pairing, mTLS or data handling is requested.

Validation approach

• Drive the broker from a shell exactly as we did: ./nvpair-ui-broker --cluster-dir <dir> from a directory holding the sibling binaries, send {"jsonrpc":"2.0","id":1,"method":"discovery:subscribe"} and workloads:subscribe, run one POST /api/chat through the proxy, observe workloads:upsert with scheduledOn.
• For the version field: create a node, read node-id.json, confirm the field; start a host against a directory carrying a higher version and confirm it refuses with a clear error.
• For the header: curl -i a successful POST /api/chat through the proxy and read the header.

Confirmations

• I searched existing issues for duplicates ([Bug]: mDNS answers are sent from an ephemeral source port, so reflectors never relay node records across subnets #1, Local node's GPU/CPU/memory enrichment is never refreshed after startup #4, [Bug]: tests write the live per-user app-data directory, so a second suite run fails #48, [Feature]: Build a service version on Linux #49, [Bug]: manual nodes are persisted only by the desktop app, so a headless nvpair-tui node loses them on every restart #58 are adjacent — mDNS reflectors, enrichment refresh, test data dir, Linux service, headless manual nodes — none asks about contract stability, data-dir versioning or a served-on header).
• I agree to follow the Code of Conduct.