RAG for Your Homelab Wiki: Answers That Cite Their Source

I have written a lot of notes about my homelab, and for a long time the only way to use them was to remember they existed. Semantic search fixed the finding problem — but I still had to read four pages to answer one question. This post adds the last mile: a small service that reads those pages for me and answers in a sentence, with the sources listed underneath so I can check its work.

What retrieval already gave me, and what was missing

The local embeddings index from earlier in this series turns every section of every page into a vector — a list of numbers that captures roughly what the passage means, so a search for “boot repair” finds the page titled “Recover GRUB after a failed EFI update” even though they share no words. Ask it a question and you get back a ranked list of sections.

That is the retrieval half of retrieval-augmented generation, the technique introduced by Lewis et al. (2020) — pairing a language model with a searchable index instead of relying on what the model memorised during training. The generation half is what I was doing by hand: reading the top few hits and synthesising an answer.

So the whole job is a short pipeline. Embed the question, rank the sections, hand the winners to a model with strict instructions, and label the result.

The service that does this is about 250 lines of Node with no dependencies at all — the standard library has an HTTP server and fetch, and everything else is arithmetic. It runs beside the index it reads, on the same small container that hosts the wiki.

The three parts worth getting right

curl -s http://10.0.0.65:11434/api/embed -d '{
"model": "nomic-embed-text",
"input": "search_query: how do I recover a locked keyring",
"truncate": true
}'

curl -s https://api.anthropic.com/v1/messages \
-H 'x-api-key: YOUR_API_KEY' \
-H 'anthropic-version: 2023-06-01' \
-H 'content-type: application/json' \
-d '{
  "model": "claude-haiku-4-5",
  "max_tokens": 1024,
  "system": "Answer ONLY from the numbered excerpts. Cite them as [1], [2].",
  "messages": [{"role": "user", "content": "<excerpts>\n\nQuestion: ..."}]
}'

The honest arithmetic on running it locally

I wanted this fully local. I measured it instead of assuming, and the numbers made the decision for me.

Roughly three and a half seconds against a hundred and thirty-eight, and the slow one had to be handed a single excerpt rather than six to fit its context window at all. My nodes have no GPU, and reading a long prompt is exactly the work CPUs are worst at. So hosted became the default and local stayed as a per-request switch — genuinely useful when a question touches something I would rather not send anywhere, and worth re-testing the day I put a GPU in the rack.

Worth being clear about what does and does not leave the network: retrieval is local in both modes. Even on the hosted path, what goes out is the question and the handful of passages picked for it — not the wiki.

The label is the feature

Everything above is standard. This is the part I would fight for.

The search index is derived — built from the wiki, never the other way round. It can therefore be behind. Keeping derived copies honest is a running theme in this series, and the rule is always the same: a derived thing must know, and report, which revision it represents.

So every response carries three fields: the revision the index was built from, the live revision of the wiki right now, and whether they differ. When they differ, that fact is also injected into the model’s instructions, so the answer itself opens by warning you rather than leaving it to a badge you might not look at.

curl -s http://10.0.0.76:9113/health

# {
#   "ok": true,
#   "revision":       "64dc195...",   <- what the index knows
#   "canonical_head": "64dc195...",   <- what the wiki actually is
#   "stale": false,
#   "chunks": 1114, "pages": 165
# }

One wrinkle worth passing on. Reading the live revision by shelling out to git did not work: the service runs as its own unprivileged user, and Git refuses to operate on a repository owned by somebody else, failing with fatal: detected dubious ownership in repository at '<path>' unless you add a safe.directory exception. Rather than widen that (Git’s own documentation explains it exists to stop a repository you do not control from executing configuration you did not write), I read the ref files directly — HEAD, then the branch ref, then packed-refs as a fallback. A dozen lines, no shell, no exception, and the reader never gains a capability it does not need.

Read-only by construction, not by good intentions

This thing sits next to my knowledge base with a language model attached. The safest version of that is one that cannot write, so there is no write path, no rebuild trigger, and no code that mutates the repository at all — the only file operations in it are reads.

Then the ordinary hardening: no new privileges, no capabilities, a memory ceiling, and validation on everything a caller can send (a length cap on the question, a cap on how much history it will accept, a bounded result count, and a pattern check on the topic filter, with oversized request bodies dropped rather than buffered).

What it feels like to use

The honest test is not a benchmark, it is the Sunday-evening question you would otherwise answer by opening four tabs. Mine tend to be things like “what was the deal with the NAS double hop again?” — and the useful part of the reply is not the paragraph, it is the two page names underneath it, because that is where I go next.

I put the same endpoint behind a tab in my homelab dashboard app, where the citations render as chips you can tap to see the passage, and the staleness flag renders as a small amber badge on the answer. Same three fields, just wearing a UI.

If you already have the index, this is an afternoon. The paired playbook — A cited RAG endpoint over your Markdown wiki — has the whole retrieve-then-generate core in one copy-paste file. And if you have not built the index yet, start there instead: the retrieval half is the half that decides whether any of this is worth reading, and no amount of clever prompting rescues a search that returned the wrong pages.

Related posts:

• Semantic Search for Your Notes, Running Locally — the embeddings index this reads; build it first
• Prove Your Homelab Docs Are Actually Up to Date — where the revision-labelling discipline comes from
• CPU-Only Ollama Cluster on Proxmox LXC: 3-Node Setup with Load Balancing — the local inference nodes doing the embedding
• Make Your AI Agents Read the Docs First, Every Time — another consumer of the same index, on the retrieval-only path
• Building a Native Proxmox Dashboard in Flutter: Linux Desktop + iOS — the app that renders these answers and their citations
• Track AI Token Spend in Grafana: Claude, Codex, and Ollama — watching the spend once a hosted model is in the loop
• Never Lose a Homelab Note Again: A Git + Markdown Vault — the vault everything here is derived from
• Open WebUI Advanced: RAG, Pipelines, and Custom System Prompts — a general chat front end over the same Ollama cluster