homelab-agent

A platform for running a team of AI agents on a single server. Nine resident agents — five build agents (sysadmin, developer, research, writer, security) plus doc-health, memory-sync, jobsearch and fleet — work semi-autonomously or fully unattended, coordinating through a task queue and communicating over Matrix. Each agent gets a scoped tool surface controlled by a manifest, persistent multi-tier memory backed by open-source infrastructure (qmd for semantic search, OpenSearch for full-text), and an event ledger that tracks every cross-agent handoff.

The agents build the platform. Research plans a feature, developer writes the code, writer documents it, security audits the result — then the new tool becomes available to the agents that built it. searxng-mcp, scoped-mcp, and githost-mcp were all built this way.

This repo documents every piece of that stack and the decisions behind it. Use it as a reference to build your own.

The host is forge — a Minisforum MS-A2 running Debian 13 with 90+ containers and 30+ PM2 background services.

The earlier claudebox-era build is archived at tag archive/claudebox-v1.

---

Start Here

Three entry points depending on what you're after.

Building your own? Read this page for the architecture, then explore docs/components/ for per-service configuration detail. The Docker stacks in docker/ have .env.example files ready to copy — the component docs are structured so you can feed them to an AI agent and adapt to your setup.

Operating or extending an existing setup? Jump straight to docs/components/ — 111 per-service docs covering config, ports, dependencies, health checks, and restart procedures.

Wiring up agents? Start with AGENTS.md for the agent roster and tool scoping model, then look at the sanitized manifests in manifests/ and Claude Code project configs in claude-code/.

---

Architecture

Three layers, each independently useful. You can run just the Docker services without agents, or add agents later.

┌────────────────────────────────────────────────────────────────┐
│  Layer 3: Multi-Agent Claude Code Engine                       │
│  9 resident agents · scoped-mcp · Matrix dispatch             │
│  agent-bus · memory pipeline                                   │
├────────────────────────────────────────────────────────────────┤
│  Layer 2: Docker Service Stack (90+ containers, 30+ stacks)    │
│  SWAG/Authentik · Ollama (NVIDIA GPU) · Langfuse · SigNoz      │
│  Synapse · SearXNG · OpenSearch · Vikunja · NATS               │
├────────────────────────────────────────────────────────────────┤
│  Layer 1: Host                                                 │
│  Minisforum MS-A2 · AMD Ryzen 9 9955HX (16c/32t) · 96 GB      │
│  NVIDIA RTX 2000 Ada · 5.4 TB NVMe · Debian 13 trixie         │
└────────────────────────────────────────────────────────────────┘

Layer 1 — Host

Machine	Minisforum MS-A2
CPU	AMD Ryzen 9 9955HX — 16 cores / 32 threads
RAM	96 GB DDR5
Storage	1.8 TB + 3.6 TB NVMe (Btrfs)
GPU	NVIDIA RTX 2000 Ada (Ollama inference) + AMD iGPU (Grafana rendering)
OS	Debian 13 trixie

Layer 2 — Docker Services

Roughly 95 running containers across 31 compose stacks (counted 2026-10-27; both numbers drift as stacks are added and retired). Full per-service documentation is in docs/components/.

Category	Key Services	Count
Foundation	SWAG (reverse proxy + SSL), Authentik (SSO), OpenBao (secrets)	7
Observability	Grafana + Loki + Alloy, SigNoz (APM), Langfuse (LLM traces)	23
AI & Search	Ollama (local inference), SearXNG, Firecrawl, Reranker	19
Memory	qmd (semantic), OpenSearch (full-text), scribe (digests)	1 (qmd and scribe run under PM2)
Agent Infra	Synapse (Matrix), NATS (event bus), task-queue-mcp	9
CI/CD	Woodpecker CI, PatchMon (patch tracking), Renovate	8
Apps	Nextcloud, LibreChat, Vikunja (tickets), Homepage, browser tools	28

Deployment order and stack dependencies are documented in docker/README.md.

Layer 3 — Multi-Agent Engine

This is the part that ties everything together. Nine resident agents run as scoped Claude Code projects, each with a manifest-controlled tool surface and (for most) a dedicated Matrix room. The diagram shows the five build agents; AGENTS.md is the full roster and the source of truth for the count.

flowchart TB
    operator["Operator\n(Matrix client or browser)"]

    sysadmin["sysadmin\nDocker, apt, services"]
    research["research\nplanning, upstream docs"]
    developer["developer\ncode, MCP servers, PRs"]
    writer["writer\ndocs, READMEs, runbooks"]
    security["security\naudits, triage, remediation"]
    sysadmin & research & developer & writer & security -- "notify via matrix-mcp" --> operator

    subgraph "Each agent gets"
        manifest["Manifest\n(allowed tools, rate limits,\nargument filters, HITL gates)"]
        scoped["scoped-mcp proxy"]
        memory["Persistent memory\n(3-tier notes + vector search\n+ knowledge graph)"]
        bus["agent-bus\n(event ledger → NATS)"]
    end

    sysadmin & research & developer & writer & security --> manifest
    manifest --> scoped
    scoped --> backends["Backend MCP servers\n(system-ops, githost, dockhand,\nsearxng, signoz, qmd, ...)"]

How it works:

• scoped-mcp reads each agent's manifest and proxies only the allowed tools. Agents never see credentials — secrets are injected from OpenBao (Vault-compatible API) at proxy level. Rate limits, argument filters, and response redaction are enforced per-agent.

• Matrix notifications: Matrix is notify-only. Agents post messages to their rooms through matrix-mcp. The Matrix dispatcher, which routed operator messages from Matrix into agent sessions, was retired 2026-10-29 along with the task-queue and admin bots.

• Persistent memory — a three-tier system (session → working → distilled) with three search paths: semantic via qmd, full-text keyword via OpenSearch, and structured metadata queries.

• agent-bus logs every cross-agent event (handoffs, task completions, audit requests) to a JSONL trail, federated to NATS JetStream.

• task-queue handles cross-agent work — research hands off build plans to developer, developer hands off doc updates to writer, writer files tickets back when gaps are found.

---

What's In This Repo

docs/components/   — Per-service operational reference (111 docs)
docs/operations/   — Operational runbooks
CHANGELOG.md       — Build history summary
docker/            — Docker Compose stacks with .env.example templates
scripts/           — Maintenance and monitoring scripts
manifests/         — Sanitized agent manifest examples
claude-code/       — Claude Code project configs and CLAUDE.md examples
pm2/               — PM2 ecosystem config and process documentation

Prerequisites

To replicate this stack:

• A machine with 32 GB+ RAM (96 GB recommended if running several concurrent agents with local LLMs)
• An NVIDIA GPU for local Ollama inference, or a remote Ollama API endpoint
• Debian/Ubuntu with Docker CE + Compose
• A domain name — SWAG uses DNS-01 validation via Cloudflare (no port forwarding required)
• Claude Pro or Max subscription + Anthropic API key (for the agent engine)

The observability and service stacks run without the GPU. The agents run without local Ollama — they call the Anthropic API directly. Local inference matters for embeddings, reranking, and query expansion, and for cost when running many concurrent agent sessions.

License

MIT