Case study / Self-hosted AI
Homelab Agent
A credential-free AI client that can reason across a private homelab through small, scoped, auditable tool services.
The problem
AI is useful only when it can reach evidence safely.
A chat model can explain a server problem, but without current state it is guessing. Giving one model broad credentials creates the opposite problem. Homelab Agent separates reasoning from access so different models can use the same narrow, observable capabilities.
Architecture
Thin client, stateful server, scoped hands.
- The client is portable and contains no infrastructure secrets or database.
- Server-side connectors each own one concern such as fleet inspection, containers, networking, code, or the personal wiki.
- Read and write operations are separated; dangerous actions remain confirmation-gated.
- A collector records append-only infrastructure snapshots and emits edge-triggered alerts.
- The same tool plane works with a private local model and stronger external coding agents.
Key decision
One tool protocol, multiple reasoning engines.
Capabilities are not rebuilt for each chat product. Local and frontier models call the same contracts, so stronger reasoning does not require a second privileged path. The architecture also makes failures visible: tool output is bounded, errors are explicit, and live state is read back after changes.
The knowledge layer
Chats forget; the system compounds.
An interlinked Markdown wiki holds biography, projects, operating rules, and source provenance. Git owns implementation. Backlogs hold deferred work. Together they let a new session start from durable context rather than a copied transcript.
Public boundary
Show the method without publishing the map.
This case study intentionally omits internal addresses, ports, hostnames, credentials, live inventory counts, and detailed topology. The useful idea is the separation of reasoning, tools, evidence, and durable knowledge.