homelab-agent: A Complete Reference Architecture for Building a Private Multi-Agent AI Platform

homelab-agent is a complete multi-tier architecture reference implementation designed to build a fully functional private AI platform in a home lab environment. Through its three-tier architecture, it enables persistent context, multi-agent collaborative workflows, and dedicated agents, allowing AI to truly understand and manage your infrastructure. Data stays local, protecting privacy while providing deep integration capabilities that cloud services cannot match.

The core concept of homelab-agent is to enable AI to no longer start from scratch in each session, but to have persistent memory about the environment, actively call tools to manage servers, and execute specific tasks through specially built agents. This is not just "using AI to write scripts"; it is an intelligent system that runs continuously, accumulates knowledge, and deeply integrates with infrastructure, with all data running on local hardware to ensure privacy and security.

Tier 1: Host and Core Toolchain

The base layer uses a dedicated mini PC (e.g., GMKTec K11) running Debian 13 and Claude Desktop. The core is MCP server integration, providing real-time access to 17 services (monitoring, storage management, development tools, etc.).

Tier 2: Self-Hosted Service Stack

Deploy LibreChat (multi-user frontend + dedicated agents), SWAG/Authelia (security authentication), observability stack (Grafana + InfluxDB + Loki), and dedicated components like CloudCLI and SearXNG via Docker.

Tier 3: Multi-Agent Claude Code Engine

It has scoped memory, background jobs, and automatic knowledge accumulation capabilities. Agent collaboration is achieved through CLAUDE.md structured knowledge organization and NATS JetStream.

1. Persistent Context System: Evolving from markdown records to a structured repository, allowing AI to have persistent memory of the environment, shifting interactions from explaining settings to direct commands.
2. Version-Controlled Infrastructure: Everything touched by AI is under git version control, changes are auditable and rollbackable, and collaboration has a single source of truth.
3. Modular Design: Each component can be used independently or combined, with documentation providing independent value, integration value, and adoption priority ratings.

Infrastructure Operations

Query Netdata metrics, TrueNAS storage status, Unraid container health, etc., via MCP integration.

Development Workflow

Manage GitHub repositories, semantically search code documentation, and use the CloudCLI in-browser interface.

Dedicated Agent: Job Search Assistant

Implement multi-source job crawling, resume scoring, application tracking, email reminders, and other functions.

Autonomous Build Pipeline

Includes components like trigger-proxy and task-dispatcher, supporting secure workflow execution.

1. Ollama Queue Proxy: Three-level priority queue, client API authentication, model-aware routing, Valkey embedding cache, etc.
2. Semantic Search Architecture: qmd hybrid search (BM25 + vector + LLM reordering), Hister memory search (covering 500+ files).
3. Knowledge Graph: Build a temporal knowledge graph with Graphiti + Neo4j to capture infrastructure topology, maintained by memory-flush and memory-sync.

Recommended incremental deployment path:

1. Phase 1: Layer1 Foundation (dedicated host + Claude Desktop + core MCP server)
2. Phase 2: Layer2 Core (LibreChat + SWAG/Authelia + SearXNG)
3. Phase3: Observability (Grafana stack + monitoring integration)
4. Phase4: Advanced Features (agent bus, knowledge graph, Temporal workflows) Even with only Layer1, you can achieve an upgrade in direct interaction between AI and infrastructure.

homelab-agent represents cutting-edge practice in building personal AI infrastructure, transforming LLMs from "conversation tools" into "infrastructure operators". It provides a valuable reference architecture for tech enthusiasts, home lab hobbyists, and enterprise users. Its modular design supports incremental adoption, and its rich documentation and active updates make it a sustainable learning resource.