Home

HomePilot Agent — AI Orchestration for Homelab Management

HomePilot Agent is the AI orchestration layer for HomePilot homelab management. It brings together a local LLM, workflow automation, monitoring, and chat interfaces into a single docker compose up stack.

What It Does

• Automates homelab operations through n8n workflows triggered by webhook, cron, or chat
• Runs local LLM inference (Qwen3-14B) for privacy-preserving AI assistance
• Monitors infrastructure via Zabbix — Proxmox VE nodes, containers, CVE tracking
• Sends real-time alerts to Matrix rooms on problems, drift, and security vulnerabilities
• Provides conversational interface via Telegram and Matrix bots
• Manages calendar-driven changes through CalDAV integration (Radicale)

Stack Components

Service	Purpose	Profile
n8n	Workflow engine, personal agent, webhooks	core
Qwen3-14B (llama.cpp)	Local LLM inference, GPU-accelerated	gpu
BGE-M3 (llama.cpp)	Text embeddings, GPU-accelerated	gpu
Zabbix	Infrastructure monitoring, alerting	monitoring overlay
SearXNG	Self-hosted web search API	core
Radicale	CalDAV calendar for scheduled changes	core
Whisper	Speech-to-text	voice
Piper	Text-to-speech	voice

Quick Start

# 1. Clone the repo
git clone https://github.com/mtclab/homepilot-agent-public.git
cd homepilot-agent-public

# 2. Configure environment
cp .env.example .env
# Edit .env — fill in all required values

# 3. Download the LLM model
scripts/download-model.sh

# 4. Start core services
docker compose up -d

# 5. (Optional) Start full stack with GPU + voice
docker compose --profile gpu --profile voice up -d

See Deployment for full setup details.

Architecture Overview

┌─────────────┐  ┌─────────────┐  ┌──────────┐
│  Telegram /  │  │   Matrix    │  │  Webhook  │
│   Chat UI    │  │    Room     │  │   (HP)    │
└──────┬──────┘  └──────┬──────┘  └─────┬─────┘
       │                │                │
       └────────────────┼────────────────┘
                        │
                   ┌────▼────┐
                   │   n8n   │  Workflow orchestration
                   └────┬────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
   ┌────▼────┐   ┌─────▼─────┐   ┌────▼────┐
   │ Qwen3   │   │ HomePilot  │   │ Zabbix  │
   │ LLM     │   │ MCP Server │   │ Monitor │
   └─────────┘   └────────────┘   └─────────┘
                        │
                   ┌────▼────┐
                   │ Proxmox │
                   │   VE    │
                   └─────────┘

Screenshots

Wiki Pages

Page	Content
Deployment	Docker Compose setup, env vars, GPU config, first-run
Monitoring	Zabbix setup, Proxmox monitoring, CVE tracking, alerting
Workflows	n8n workflows, morning briefing, Matrix bridge, webhook events
Security	Hardening, least-privilege, firewall, VPN, agent security

Key Concepts

• MCP Integration: n8n workflows call HomePilot MCP server for infrastructure operations (read-only and read-write tokens)
• Artifact Lifecycle: HomePilot proposes changes → n8n notifies Matrix → human approves in web UI → change applied
• Dual-Channel Alerts: Zabbix sends alerts to Matrix (real-time) and email (critical severity)
• Local-First LLM: All inference runs on local GPUs — no data leaves your network

Repository

github.com/mtclab/homepilot-agent-public