HomeAgents platform overview
Overview
HomeAgents is the AI platform I run at home. It lives on one server and covers chat, coding agents, document memory, web search, personal finance and a no code app builder. Each of those has its own Docker Compose stack and its own repository. This repository explains what the parts are and how they fit.
Two decisions hold it together. First, every model call goes through one gateway, so the applications never know which provider is behind a model name. Second, long term memory is one vector collection with a domain label, so different assistants share the storage but not each other’s memories.
I wrote the README so that a stranger could clone the stack and run it. It has the diagram, the port table and the design principles. The principles are simple. Pin the images, keep secrets in one file, embed locally so recall is free, and give every repository one job.
The platform grew out of my n8n pipelines and my home server setup. It is where I put the lessons from both into one place.
Problem
I wanted one AI platform for my household that runs on a single home server. It needed chat, coding agents, document memory, web search, personal finance and an app builder. Each part had to stay independent, but they all had to work together without a mess of provider keys and open ports.
Approach
- I gave each part its own Docker Compose stack and its own repository, so I can start, change or remove one without touching the others.
- I wrote this repository as the map. It explains what the parts are and how they connect.
- I made two design decisions first and built everything else around them.
- I kept the README practical, with an architecture diagram, a port table and the exact steps to clone and run.
Architecture and design decisions
- Every model call goes through one LiteLLM gateway. Applications only see virtual model names: fast, coder, architect, premium and openai-fallback.
- Switching a provider or a budget is a single file edit. No user interface has to change.
- Long term memory is one Qdrant collection with a domain field on every entry. A personal assistant and a work assistant share the same infrastructure without sharing context.
- Chat runs on LibreChat (port 3080) and app building on the Dify console (port 8085). Both talk to the gateway.
- Memory runs on Qdrant (6333) with local embeddings from TEI (8081). The qdrant-mcp server (8765) gives the assistants tools to store and search it.
- Search runs on SearXNG (8082) with a web search MCP server. Finance runs through an MCP server for Firefly III (3002). The OpenHands coding agent listens on port 3000.
- All of these share one external Docker network called ai-platform-net, so services find each other by name.
Reliability and performance
- Every published port binds to 127.0.0.1, so nothing is reachable from the local network by default.
- Secrets live in one git-ignored .env file.
- Images are pinned to exact versions, so a rebuild does not change what runs.
- Embeddings run locally on the CPU, so searching my documents costs no API credit.
- I keep one concern per repository, which keeps each stack small enough to understand and restore on its own.
Outcomes
- Six repositories are documented as one architecture with a diagram, a port table and a clone and run sequence.
- One gateway serves every application with five virtual models.
- One vector collection serves several domains without mixing their context.
- Nothing in the platform is exposed to the local network by default.
- The platform runs on one home server with about 16 GB of RAM.
- The repository is public and MIT licensed.
Known gaps
- This repository is the map. The code and the detailed configuration live in the other repositories.
- I have no measurements for speed, memory use under load or answer quality.
- I have no cost figures for the model calls. The budget limits exist, but I do not publish what they cost.
- The platform is built for one household. I have not tested it with several users or on several servers.
- I do not claim it is hardened beyond the loopback binding and the secret handling described above.