isputnik.faces

An add-on for isputnik.home: its face recognition engine. It finds the faces in a photo and describes each one, behind the home server, which keeps every face, name and person and draws every screen. It requires the isputnik.home container, is installed beside it and is reached only through home's /faces gateway; this server has no pages and no data: a photo goes in, its faces come out, nothing is remembered.

Why it is a container of its own: the ONNX runtime and the two InsightFace models are ~450 MB that change about never, and home releases every few days. Here they are pulled once. The design is home's docs/face-engine-plan.md.

Status: 0.1.0, alpha. CPU only; a CUDA image is planned.

The contract, from this side

• Reached only by home's server, signed with GATEWAY_SECRET in X-Isputnik-* headers (home's docs/apps-platform-plan.md → The contract); without the secret a request is anonymous. Home's gateway forwards only the admin window to browsers; /detect is called by home's own scanner.
• The model id (buffalo_l/w600k_r50) is the one home stamps on its face rows, so an install that switches from in-process recognition re-embeds nothing.
• The engine never calls home.

Running it

docker network create isputnik          # once, shared with isputnik.home
docker run -d --name isputnik-faces --network isputnik \
  -e GATEWAY_SECRET=<the secret from Control panel → Settings › Apps → Faces> \
  ghcr.io/isputnikdotnet/isputnik.faces:latest

Then in isputnik.home: Control panel → Settings › Apps → Faces, address http://isputnik-faces:4400 (or http://<host IP>:4400 with the port published, http://<its IP>:4400 on br0 with a fixed IP), paste the same secret, Test connection. The image is ghcr.io/isputnikdotnet/isputnik.faces and, the same bytes, isputnikdotnet/isputnik.faces on Docker Hub; every release tag publishes both.

Unraid — the repository carries a Community Applications template, isputnik-faces.xml, listed in CA as isputnik-faces. It publishes port 4400 on bridge (safe: without the secret every request is answered 401), mounts nothing, and asks for the gateway secret, which is made in home first because the field is required.

Developing

npm install
npm run fetch:face-model     # the 167 MB recogniser, verified by SHA-256
npm run dev                  # :4400, no secret = the developer identity
npm test                     # the route tests; detection too once the model is there

To point a home checkout at it: FACES_URL=http://127.0.0.1:4400 and the same FACES_GATEWAY_SECRET / GATEWAY_SECRET on both.

Licence

AGPL-3.0-only, like isputnik.home. The models are InsightFace's (buffalo_l: SCRFD-500MF and the w600k_r50 ArcFace recogniser), under their own terms.