homelab-agent

I run a multi-user AI platform out of a mini PC in my homelab. Claude has persistent context about my infrastructure, live tool access to my servers, purpose-built agents for specific tasks, and a web frontend accessible from any browser on the network. This repo documents the full build.

What This Is

This is more than "I use AI to write scripts." It's a three-layer platform: a dedicated host running Claude Desktop with MCP server integrations for direct infrastructure access, a self-hosted Docker stack with LibreChat as the multi-user frontend and supporting AI services, and a multi-agent Claude Code engine with scoped memory, background jobs, and automated knowledge accumulation.

The LibreChat frontend is where the platform shows its depth. It's not just a chat UI — it hosts specialized agents, each configured with its own tools, context, and purpose. The first: a job search agent with multi-board scraping, resume scoring, and application tracking. More are being added. Any browser on the network can access the platform; anyone with an account can use the agents.

What makes it work over time is the memory system. Claude doesn't start from zero every session. It loads infrastructure context, recalls relevant decisions from past work, and accumulates knowledge automatically through nightly memory sync. Add the version-controlled infrastructure (everything the AI can touch is in git), and you have a system that can operate alongside you without being a liability.

Modular by design. Take the whole thing or just the parts that fit your setup. The system rewards customization — the more you shape it to how you actually work, the more useful it gets.

How This Started

I watched a TechnoTim video on TrueNAS and Docker, needed a backup script, and used Claude to write it. The script worked, but Claude kept asking me the same questions about my setup every session. So I started writing down my infrastructure in markdown files and feeding them as context. That context system grew into a structured repository — profiles, preferences, infrastructure docs, project instructions — which I started calling the "prime directive."

Once Claude had persistent context about my environment, the interactions changed. Instead of explaining my setup every time, I could say "check if the Plex container is healthy on unraid" and it already knew unraid's IP, what monitoring tools were available, and how my Docker stacks were organized. That was the inflection point.

I built a dedicated mini PC (claudebox) to run Claude Desktop full-time with MCP tool integrations — direct access to Netdata, Grafana, GitHub, the filesystem, and a browser. Then I layered on a self-hosted service stack: reverse proxy with SSO, a multi-provider chat UI with purpose-built agents, semantic search over all my docs and repos, and a Claude Code web interface. On top of that, a multi-agent Claude Code engine with scoped memory, background jobs, and automated knowledge sync.

It grew organically from "AI writes me a script" to "AI operates alongside me as infrastructure."

Recent Updates

See CHANGELOG.md for the full build history.

• 2026-03-29 — Inter-agent event bus: every cross-agent event (handoffs, audit requests, task failures, artifact writes) now flows through a shared FastMCP event log federated to NATS JetStream. First unified audit trail across the multi-agent system — any agent can query another’s activity without reading its memory files directly.
• 2026-03-29 — Durable multi-phase automation: a Temporal worker bridges the durable execution platform to Claude Code agents via async activity completion. Each build phase is a Temporal activity — if the system restarts mid-build, it picks up at the last incomplete phase. Agents signal phase completion back to Temporal via task token handoff, not polling.
• 2026-03-29 — Real-time semantic memory: memsearch-watch re-indexes all memory directories within 5 seconds of any write, making context written mid-session immediately searchable. New archival-search skill queries all three memory tiers in one pass and returns results labeled by source tier.
• 2026-03-28 — Helm Dashboard plugin for CloudCLI: browser-based monitoring tab with eight panels — agent status, memory browser, handoff queue, knowledge graph, PM2/Docker infrastructure, build progress, Plane integration, and WebSocket live updates. Pairs with auto mode configuration for walk-away builds — environment rules for trusted operations, per-project SSH permissions for the helm-build agent, and a CloudCLI SDK patch to default sessions to auto mode.
• 2026-03-17 — Knowledge graph: Neo4j + Graphiti MCP temporal knowledge graph deployed. Agents can now query infrastructure topology and relationships — “what connects to SWAG?”, “what runs on atlas?” — rather than searching flat text. Fed automatically by memory-flush (real-time) and memory-sync Step 5b (nightly batch). Prescribed entity ontology: Service, Host, Network, Configuration, Agent, User, Port.

Architecture

The system has three layers. Each is independently useful — you don't need all three.

┌─────────────────────────────────────────────────────────┐
│  Layer 3: Multi-Agent Claude Code Engine                │
│  CLAUDE.md hierarchy · scoped memory · memsearch        │
│  knowledge graph · agent-bus · Temporal · mem pipeline  │
├─────────────────────────────────────────────────────────┤
│  Layer 2: Self-Hosted Service Stack (Docker)            │
│  SWAG/Authelia · LibreChat · purpose-built agents       │
│  qmd · CloudCLI · SearXNG · Grafana · NATS · Temporal   │
├─────────────────────────────────────────────────────────┤
│  Layer 1: Host & Core Tooling                           │
│  Debian mini PC · Claude Desktop · MCP servers          │
│  Guacamole remote access                                │
└─────────────────────────────────────────────────────────┘

Layer 1 — Host & Core Tooling

The foundation is a dedicated machine running Claude Desktop with MCP (Model Context Protocol) server integrations. MCP gives Claude direct, structured access to your infrastructure tools — not copy-pasting outputs into a chat window, but live tool calls.

Hardware: GMKTec K11 mini PC — AMD Ryzen 9 8945HS, 32GB RAM, 2TB NVMe. Plenty for local embeddings and multiple Docker containers. Any modern mini PC or repurposed desktop works.

OS: Debian 13 (trixie). Nothing special about the choice — stable, familiar, good Docker support.

Claude Desktop runs as the primary AI interface, with MCP servers providing tool access:

For config patterns, standalone value ratings, and a prioritized adoption path, see mcp-servers/README.md.

Guacamole provides browser-based remote desktop access to the machine. Useful when you're away from the desk but need to interact with Claude Desktop's GUI.

Standalone value: Even without Layers 2 and 3, a dedicated machine running Claude Desktop with MCP servers is a significant upgrade over using Claude in a browser tab. The MCP integrations alone — being able to say "check disk health on unraid" or "query Grafana for the last hour of CPU on atlas" — change how you interact with your infrastructure.

Layer 2 — Self-Hosted Service Stack

Docker containers on the same host, fronted by a reverse proxy with SSO. These provide web-accessible AI tools for the whole household or team, not just whoever is sitting at the Claude Desktop session.

All containers share a single Docker network. SWAG handles SSL termination and routes chat.yourdomain, auth.yourdomain, cloudcli.yourdomain, etc. to the appropriate container.

Standalone value: The SWAG + Authelia + LibreChat stack is useful even without Claude Desktop or the agent engine. LibreChat gives you a self-hosted ChatGPT-like interface that works with multiple AI providers, and Authelia keeps it locked down.

Layer 3 — Multi-Agent Claude Code Engine

This is where it gets opinionated. Claude Code (the CLI tool) supports project-scoped context via CLAUDE.md files and experimental agent teams. Combined with semantic memory search and PM2-managed background jobs, this creates a persistent, multi-agent system that accumulates knowledge over time.

CLAUDE.md Hierarchy:

~/.claude/CLAUDE.md                          ← Root context (loaded every session)
~/.claude/projects/homelab-ops/CLAUDE.md     ← Infrastructure management agent
~/.claude/projects/dev/CLAUDE.md             ← Code development agent
~/.claude/projects/research/CLAUDE.md        ← Technical research agent
~/.claude/projects/memory-sync/CLAUDE.md     ← Automated knowledge distillation

The root CLAUDE.md contains infrastructure topology, key paths, and global rules. Each project CLAUDE.md adds domain-specific context, available tools, and conventions. When you start a Claude Code session in a project directory, it loads the root + project context automatically.

Scoped Memory:

~/.claude/memory/
├── shared/              ← Cross-agent knowledge (infrastructure decisions, system context)
└── agents/
    ├── homelab-ops/     ← Infra-specific learnings
    ├── dev/             ← Development notes
    └── research/        ← Research findings

Agents read from shared + their own directory, write to their own directory. Cross-agent knowledge goes to shared. This prevents context bleed — the dev agent doesn't need to know about last week's disk replacement on unraid.

memsearch provides semantic search over the memory directories using local sentence-transformer embeddings and a vector database. The Claude Code plugin auto-injects relevant memories at session start and on each prompt. No API keys, no cloud services — runs entirely on the local CPU. memsearch-watch (PM2, always-on) keeps the index current by re-indexing all memory directories within 5 seconds of any write — so context captured mid-session is immediately searchable without waiting for a nightly batch. The archival-search skill provides a unified query across all three memory tiers (session, working, distilled) in a single pass, with results labeled by source tier. See docs/components/memsearch.md for configuration details.

Graphiti knowledge graph adds structured relationship queries on top of the flat-file memory system. A Neo4j-backed temporal graph captures infrastructure topology — which services run on which hosts, what depends on what, how the architecture evolved. Fed automatically by real-time memory-flush and nightly memory-sync batch ingestion. Agents query it with search_memory_facts and search_nodes when they need relational answers rather than text search. See docs/components/graphiti.md.

agent-bus is the inter-agent event ledger — a FastMCP server that logs all cross-agent events (handoffs, audit requests, task completions, failures) to a JSONL audit trail and federates them to NATS JetStream. Every coordination action between agents leaves a durable, queryable record. This is what makes multi-agent workflows debuggable: when something goes wrong, the full event sequence is preserved. See docs/components/agent-bus.md.

Temporal provides durable workflow execution for long-running, multi-phase build processes. If a workflow is interrupted mid-phase (system restart, transient error), Temporal resumes from the last checkpoint rather than starting over. The Helm build automation runs through Temporal — each build phase is an activity with heartbeating and timeout guarantees. See docs/components/temporal.md.

PM2 Background Agents:

See pm2/ecosystem.config.js.example for full configuration including an optional upstream issue watcher.

Standalone value: The CLAUDE.md hierarchy alone is worth adopting. Even without memsearch or the background agents, giving Claude Code structured context about your infrastructure dramatically improves the quality of its responses. Start with a root CLAUDE.md and one project, expand from there.

Purpose-Built Agents

LibreChat isn't just a chat interface — it's the platform that hosts specialized agents, each configured with their own MCP servers, system prompt, and domain context. The difference from a generic AI chat: these agents know their job, have the right tools wired up, and keep state across sessions.

Job Search Agent — the first purpose-built agent in the stack. Backed by its own FastMCP server with tools for multi-board job scraping, resume scoring against job descriptions, and application tracking in Postgres. A user can ask "find senior DevOps roles remote in the US, score them against my resume, and add the top five to the tracker" and get back structured results — not a list of links.

The agent/platform model means adding a new agent is a matter of writing a FastMCP server and configuring it in LibreChat. The infrastructure (reverse proxy, SSO, memory, search) is already there. More agents are being added as new use cases emerge.

See docs/components/jobsearch-mcp.md for the job search agent's architecture and the pattern for building additional agents.

The job search agent is what my situation needed. Someone else might build a home energy monitoring agent, a media request agent, something for tracking a health condition, or an agent scoped entirely to their homelab infrastructure. The platform doesn't prescribe what agents you build — it provides the infrastructure (auth, reverse proxy, memory, search) and gets out of the way. The useful thing isn't the job search agent specifically; it's that the slot exists and you can fill it with whatever fits your life.

The Memory / Context System

This is the connective tissue that makes the whole thing more than the sum of its parts. Most people's experience with AI assistants is stateless — every conversation starts from zero. This system has five layers of persistent context:

1. Prime directive repo — Stable configuration: infrastructure docs, project instructions, profile/preferences, deployment scripts. Loaded at session start via CLAUDE.md references and qmd search. This is the source of truth.

2. Core context — An always-visible 40-line context block injected at every session start. Contains the user profile, active projects, key constraints, and recent decisions. Sits above the context window's compression threshold so critical facts never scroll out mid-session.

3. Per-agent scoped memory — Session summaries and learnings written by agents during their work. Organized by agent (shared/, homelab-ops/, dev/, research/) to prevent context bleed. Indexed by memsearch for automatic recall in future sessions. memsearch-watch keeps the index current in real time (5-second debounce) so notes written mid-session are searchable in the same session. A three-tier pipeline (session → working → distilled) ensures raw notes are reviewed, curated, and promoted to permanent storage.

4. Knowledge graph — A Neo4j-backed temporal knowledge graph (via Graphiti) that captures relationships between infrastructure entities — services, hosts, networks, agents, configurations. File-based memory handles narrative knowledge well; the graph handles "what connects to what" queries. Fed automatically by memory-flush (real-time) and memory-sync (nightly batch).

5. Documentation cache — A local library of official service documentation (42 services: Grafana, Loki, SWAG, Authentik, Compose, and more), fetched nightly, chunked by heading, and indexed in memsearch alongside session memory. Agents query cached docs during task execution instead of fetching live URLs — no network dependency, no stale training data. Managed by doc-sync-daily (PM2, 3 AM). See docs/components/doc-sync.md.

6. Automated memory pipeline — Three scheduled jobs handle different parts of the promotion cycle. memory-promote-daily (11 PM) promotes same-day session transcripts to working-tier notes using a faster model — context from the day's work is searchable the next morning. memory-pipeline (4 AM) runs memsearch compaction and qmd reindex after promotions settle. memory-sync-weekly (Mondays 7 AM) promotes 14-day-old working notes to the distilled tier, expires 90-day notes, and runs graph entity dedup. Knowledge accumulates and connects without manual curation. See docs/components/memory-pipeline.md.

The result: when I start a session on Monday, the agent already knows about the Docker stack change I made on Friday, the monitoring alert from Saturday, and the research I did on Sunday. It knows because the memory sync agent captured those events, the semantic search surfaced them as relevant context, and the knowledge graph connected them to the services they affected.

What Makes This Different

Most AI homelab setups are "I use ChatGPT to write scripts." This is a persistent, context-aware system where the AI knows the infrastructure, remembers decisions, and improves over time.

Persistent context, not copy-paste. The AI doesn't need you to explain your setup every session. It loads infrastructure docs, reads recent memory, and picks up where you left off.

Multi-user platform with purpose-built agents. LibreChat gives the whole household or team access to specialized AI agents — not just one person's Claude Desktop session. Each agent is purpose-built: specific tools, specific context, specific job.

Multi-agent with scoped memory. Different Claude Code agents handle different domains without context bleed. The homelab-ops agent knows about Docker and monitoring. The dev agent knows about git workflows and code standards. They share infrastructure knowledge but keep domain-specific learnings separate.

Automated knowledge accumulation. The memory sync agent means you don't have to manually maintain documentation. Durable decisions and learnings flow from work sessions into the persistent knowledge base automatically. A temporal knowledge graph captures the relationships between infrastructure entities, so agents can query topology and dependencies — not just search text.

Tool access, not just chat. Via MCP, the AI can directly query Netdata metrics, check Grafana dashboards, search GitHub repos, read and write files, and automate browser tasks. It's not just answering questions — it's operating.

Version-controlled infrastructure. When AI agents have filesystem access, they will edit your config files directly — compose files, .env files, proxy confs. This is powerful, but it means you need version control on everything the AI can touch. All Docker compose files in this setup live in a git repo. Every change is tracked, diffable, and reversible. This isn't optional — it's the safety net that makes AI-assisted infrastructure management viable.

Model-agnostic in practice. The core engine runs on Claude, but LibreChat supports any provider (OpenAI, Ollama, etc.). SearXNG provides self-hosted search without API keys. The architecture doesn't lock you into a single vendor.

This isn't a one-click stack. There are polished prepackaged AI homelab solutions. This is not one of them. Every component here was chosen because it fit a specific need, and those choices are visible throughout the docs. Your version will look different — because your infrastructure is different, your workflow is different, and your brain works differently.

That's the point. When you build your own version of this, the AI knows about your storage server, your monitoring setup, your backup schedule and why it runs when it does. You wrote that context down, and it accumulated over time. A prepackaged solution can't ship with that. You build it, and building it is what makes it work.

Planned Additions

The platform model makes it straightforward to add new integrations as new use cases emerge. On the roadmap:

Home Assistant — pulling device state and automation context into Claude's awareness. The goal is agents that understand what's happening in the house, not just on the servers.

MQTT — event-driven triggers for agents. When something happens on the network or in the house, an agent can respond rather than waiting to be asked.

Using This Repo

This repo has two audiences: humans and AI agents.

For humans: Start with this README to understand the architecture, then docs/getting-started.md for the setup path. The docs are designed so you can stop at any layer and still have a working system. Component docs in docs/components/ go deep on individual services.

For AI agents: index.md is a machine-readable navigation index of the entire repo — every file, what it covers, and task-based routing so an agent can load only the context it needs. It's designed for Claude Code, but it works with any AI that can read files.

This last point is worth calling out directly. If you want to build your own version of this stack, you can hand your AI assistant this repo and let it help you work through it:

I want to build an AI-powered homelab setup similar to the one in this repo.
Please read index.md to understand the full structure, then help me plan
which components to adopt based on my current setup.

My setup: [describe your hardware, OS, existing services]
My goals: [what you want Claude to be able to do]

The index covers every component and links to the relevant docs. Your AI can use it to ask the right questions, identify dependencies, and walk you through setup in the right order.

Prerequisites

To run the full stack, you need:

• A dedicated machine (mini PC, old desktop, VM — 16GB+ RAM recommended, 32GB if running local models via Ollama)
• Debian/Ubuntu (or any Linux with Docker support)
• Docker CE + Compose
• Node.js 20+ and npm (for qmd, cui, MCP servers)
• Python 3.11+ (for memsearch)
• A Claude Pro or Max subscription (for Claude Desktop + Claude Code)
• An Anthropic API key (for LibreChat)
• A domain name (for SWAG SSL — can be internal-only with DNS validation via Cloudflare)
• Optional: NFS server for backups (TrueNAS, Unraid, or any NFS-capable host)

You don't need all of this to get value. See docs/getting-started.md for clear stopping points where each layer is independently useful.

Repo Structure

homelab-agent/
├── README.md                        ← You are here
├── index.md                         ← Machine-readable nav index for AI agents
├── docs/
│   ├── architecture.md              ← Detailed system architecture and data flows
│   ├── getting-started.md           ← Setup guide with stopping points per layer
│   └── components/                  ← Per-component deep dives
│       ├── swag.md                  ← Reverse proxy, Cloudflare DNS, proxy conf pattern
│       ├── authelia.md              ← SSO config, file-based user backend, SWAG integration
│       ├── librechat.md             ← Setup, web search pipeline, reranker wrapper, gotchas
│       ├── searxng.md               ← SearXNG + Valkey, shared search backend
│       ├── dockhand.md              ← Docker socket access, multi-host stack visibility
│       ├── open-notebook.md         ← SurrealDB, dual-port proxy config
│       ├── cloudcli.md              ← Claude Code web UI — file explorer, git, shell, MCP management
│       ├── auto-mode.md             ← Walk-away Claude Code config — approval skip, session limits, cost guardrails
│       ├── helm-dashboard.md        ← CloudCLI monitoring plugin — agent sessions, handoff queue, live updates
│       ├── cui.md                   ← Claude Code web UI — headless monitoring, push notifications
│       ├── agent-panel.md           ← Homelab operations panel — PM2, Docker, diagnostics, files
│       ├── diag-check.md            ← Scheduled diagnostics via agent panel API, failure alerts
│       ├── grafana-claudebox.md     ← Local Grafana + InfluxDB for agent observability
│       ├── grafana-observability.md ← Loki, image renderer, Alloy dual-destination log shipping
│       ├── graphiti.md              ← Temporal knowledge graph — Neo4j, entity ontology, data flow
│       ├── nats-jetstream.md        ← Agent event bus — JetStream streams, task lifecycle events, federation
│       ├── temporal.md              ← Durable workflow engine — 5-container stack, fault-tolerant build phases
│       ├── helm-temporal-worker.md  ← Helm build worker — async activity completion, phase orchestration
│       ├── n8n.md                   ← Workflow automation — webhook triggers, agent manifest routing
│       ├── plane.md                 ← Project management integration — work items, cycles, agent dispatch
│       ├── qmd.md                   ← Semantic search, dual transport, GPU acceleration
│       ├── memsearch.md             ← Memory recall for Claude Code, plugin integration
│       ├── memory-sync.md           ← Knowledge distillation pipeline, PM2 cron
│       ├── memory-pipeline.md       ← 3-job memory schedule — real-time indexing, distillation, graph sync
│       ├── doc-sync.md              ← Local docs cache — service reference docs fetched, chunked, memsearch-indexed
│       ├── agent-workspace-scan.md  ← Hourly workspace marker validation, drift heal, CIA event emission
│       ├── agent-workspace-check.md ← Pre-edit resolver skill — two-party permission enforcement
│       ├── agent-orchestration.md   ← Multi-agent coordination — handoff protocol, session sequencing
│       ├── task-dispatcher.md       ← Agent task queue — NATS-backed dispatch, 3-phase pipeline
│       ├── agent-bus.md             ← Inter-agent event bus — FastMCP server, NATS federation, event types
│       ├── inter-agent-communication.md ← Communication patterns — handoff protocol, CIA events
│       ├── security-agent.md        ← Security audit agent — automated scanning, severity gates
│       ├── doc-health.md            ← Weekly doc audit — drift, coverage, staleness, sanitization
│       ├── ai-cost-tracking.md      ← Claude Code JSONL parser, cost metrics, Telegraf pipeline
│       ├── homelab-ops-mcp.md       ← FastMCP HTTP tool server — shell, files, processes
│       ├── claudebox-deploy.md      ← Provisioning script — full machine rebuild from NFS backup
│       ├── multi-host.md            ← Multi-host architecture — claudebox and remote build target coordination
│       ├── config-version-control.md ← Git tracking for docker/ and appdata configs
│       ├── jobsearch-mcp.md         ← Job search agent — multi-board scraping, resume scoring, tracking
│       └── backups.md               ← Backrest/restic, Claude backup, Docker appdata backup
├── claude-code/
│   ├── CLAUDE.md.example            ← Root CLAUDE.md template
│   └── projects/                    ← Per-agent CLAUDE.md examples
│       ├── homelab-ops.md           ← Infrastructure management agent
│       ├── dev.md                   ← Development agent
│       ├── research.md              ← Research agent
│       └── memory-sync.md           ← Memory distillation agent
├── docker/
│   ├── swag/docker-compose.yml      ← Reverse proxy + wildcard SSL
│   ├── authelia/docker-compose.yml  ← SSO authentication gateway
│   ├── librechat/
│   │   ├── docker-compose.yml       ← Multi-provider chat + MongoDB + Meilisearch
│   │   └── librechat.yaml.example   ← LibreChat config with web search and MCP
│   ├── firecrawl-simple/docker-compose.yml  ← Web scraper for LibreChat search pipeline
│   ├── reranker/
│   │   ├── docker-compose.yml       ← Jina-compatible reranker wrapper
│   │   ├── Dockerfile               ← FlashRank + FastAPI build
│   │   └── main.py                  ← Reranker API source (~115 lines)
│   ├── dockhand/docker-compose.yml  ← Docker stack manager UI
│   └── open-notebook/docker-compose.yml  ← AI notebook + SurrealDB
├── pm2/
│   └── ecosystem.config.js.example  ← PM2 service definitions
├── scripts/
│   ├── docker-stack-backup.sh       ← Container-safe appdata backup with notifications
│   ├── qmd-reindex.sh               ← Semantic search re-indexing
│   ├── memory-sync.sh               ← Automated knowledge distillation
│   ├── check-resources.sh           ← Health monitoring with ntfy alerts
│   └── check-dep-updates.sh         ← Dependency update checker
└── mcp-servers/
    └── README.md                    ← MCP servers in use, config patterns, adoption path

Related Repos

Contact

• Discussions: GitHub Discussions — questions, ideas, and show-and-tell
• Email: [email protected]
• Issues: GitHub Issues — bugs and doc errors

License

MIT