Skip to content

Add nodes

A node connects out to the hub over one WebSocket, so it needs no inbound port and no router changes. You add one in three moves: install the node software, pair it with the hub (which gives it its own node key), and approve it. Pairing flows and their threat model: docs/PAIRING.md in the repository.

Laptops, desktops, a Raspberry Pi or a server, amd64 or arm64. The node runs as your own user from a systemd user service, never as root, and serves only on mains power while nobody uses the machine.

  1. Install and pair with one command, as your own user:

    Terminal window
    curl -fsSL <releases-url>/latest/download/install.sh | sh -s -- --publisher <keyId>
    curl -fsSL <releases-url>/latest/download/install.sh | sh -s -- --hub https://<hub-host> --publisher <keyId>

    It installs kinherd-node and the TensorFlow Lite runtime under ~/.local (checked against the release’s SHA256SUMS), then pairs: on the same network the node finds the hub by itself, --hub names one elsewhere. --publisher names the publisher key(s) whose signed models the node accepts (Add device on the dashboard lists the hub’s keys). The node prints a code such as K7TQ-3MZA and waits.

  2. Approve on the dashboard: Add device → Approve a device, enter the code, compare the machine the hub shows (model, CPU, OS, RAM, source address) and approve. Approving the device also approves the node.

  3. The installer then starts the systemd user service and prints kinherd-node status.

The node installs the models that matching recipes name, checking every signature, benchmarks them and starts serving. … | sh -s -- --uninstall (or kinherd-node uninstall) removes everything.

To serve chat models, install llama.cpp’s llama-server, put a GGUF model in ~/.local/share/aigw-node/gguf/, then run:

Terminal window
kinherd-node up # finds llama-server and GGUF models, asks which to add, restarts the node, waits until it is online

up backs up config.json before changing it, touches only the chat model list (never the owner protections), adds nothing twice when run again, and prints the models the node serves. --yes picks the largest model that fits in half the RAM, --model FILE.gguf names one.

Without the installer (a binary you built or copied, or a Mac), the same three commands set a node up, and each is safe to run again:

Terminal window
kinherd-node pair https://<hub-host> # prints the approval URL and code, waits for your approval
kinherd-node install # systemd user service (a launchd agent on macOS), started now and at login
kinherd-node up # chat models, then waits until the hub has the node online
  1. Install the APK from your hub’s /downloads/latest/<file> links (the website’s Download page) or the project’s GitHub Releases (there is no Play Store listing): the build flavor litert2 for phones, nnapi for TVs.

  2. Create a pairing code on the dashboard: Add device → Create code (or kinherd pair -name tv). It shows a QR code with the hub address, the one-time code and the publisher keys to trust.

  3. Pair in the app: Scan QR code, or Enter a pairing code. On a TV without a camera, type the code, or provision it over adb with kinherd device add -adb <ip>:5555 -apk <apk>.

  4. Approve the node on the dashboard’s Nodes page. Nodes paired with a code start pending and get no jobs until then.

Once it connects, the hub lists the node’s models with "location": "peer:<node>". After five runs per model the node files its benchmark in the registry.

The app reaches the hub over HTTPS only: on the home network through the hub’s LAN endpoint, whose certificate it pins, and from elsewhere through the hub’s public HTTPS address.

Flavor For Runtime Accelerators APK
litert2 (default) phones LiteRT 2.3.2: CompiledModel GPU/NPU/CPU + Interpreter (XNNPACK) gpu, npu, cpu ~19.5 MB
nnapi TVs (32-bit, NNAPI NPU) LiteRT 1.4.2 Interpreter + NNAPI delegate npu, cpu ~7.7 MB

To build them yourself:

Terminal window
./gradlew assembleLitert2Debug # phone
./gradlew assembleNnapiDebug # TV

Without pairing, a node can use a node key you create by hand (dashboard → Keys → kind node, or POST /v1/admin/keys {"name":"tv","kind":"node"}; the key’s name becomes the node’s name). Keys created by hand are not pending. On Android, put it in gateway.conf:

{
"name": "pixel-7-pro", "role": "node",
"hub": {"url": "wss://<hub-host>/v1/nodes/connect", "token": "<phone node key>"},
"memoryBudgetMB": 1500, "queueSize": 4, "keepAwake": true
}
Terminal window
adb push gateway.conf /sdcard/Android/data/dev.kinherd.app/files/gateway.conf # then Stop + Start in the app

Optional keys in "hub": "certSha256" pins a self-hosted hub’s certificate instead of the system trust store.

Nodes normally install models from recipes. To side-load one, copy a model package directory to /sdcard/Android/data/dev.kinherd.app/files/models/<id>/ (Android) or ~/.local/share/aigw-node/models/<id>/ (Linux), then restart the node. The Linux node accepts only packages signed by a publisher key it trusts (requireSignature). Rejected packages are listed with the reason on the status screen and in GET /v1/models.