HomeAgents core
Overview
This is the always on base of my HomeAgents platform. It holds the model gateway, the memory, the search, the finance tools and the coding agent. The other repositories connect to it.
I split it into four compose files because I rarely need everything at once. All of them share one Docker network, so services find each other by name and the ports only open to my own machine.
The part I care about most is the model routing. The gateway has a few virtual models, such as fast, coder and architect. Every app uses those names and never a real provider model. When I want a different model or a smaller budget, I change one file.
Security is a short list of rules. Only the gateway holds provider keys, secrets live in one ignored file and the shipped example holds placeholders only.
Problem
My AI platform needed one stable base that every other part could rely on. I did not want provider keys in every app, models named all over the code or a stack that I have to start all at once. I also wanted to keep control of cost.
Approach
- I split the base into four compose files, so I can start only what I need.
- I made one gateway the single way to reach any model.
- I put every container on one shared Docker network, so services find each other by name.
- I wrote the security rules down as a short list and built the setup around them.
- I kept this repository as the place where the other repositories connect, such as the MCP servers, chat, the app builder and the ingestion worker.
Architecture and design decisions
- The core stack runs the LiteLLM gateway, Qdrant, the embedding service, the qdrant-mcp server, PostgreSQL and Redis.
- The web search stack runs SearXNG and the web search MCP server. The finance stack runs the Firefly III MCP server. The programming stack runs the OpenHands coding agent.
- All containers join one external network called ai-platform-net. Services use names like litellm:4000, qdrant:6333 and embeddings:80.
- LiteLLM exposes virtual models. Fast is for everyday chat. Coder has thinking switched on. Architect is for long planning tasks. Premium is for rare and expensive cases. There is also an OpenAI fallback.
- Each virtual model points to a real provider model. Nothing outside the gateway names a provider, so changing a model or a budget is one file edit.
- Runtime data sits in plain folders under VOLUMES and stays out of git.
Reliability and performance
- Budgets are enforced on three levels: per virtual model, per provider and through the prepaid balance of the providers themselves.
- Every published port binds to 127.0.0.1, so the services only answer to a browser on the same machine.
- Only the gateway holds provider keys. The chat app reaches it with one master key.
- The .env file is git ignored. The repository ships a .env-example with placeholders. The SearXNG signing secret comes from the environment and not from the settings file.
- The setup says clearly that qdrant_data and postgres_data are the minimum to back up.
- Because the stacks are separate, one can be stopped or broken without taking down the others.
Outcomes
- One gateway gives every application the same five virtual models.
- Budgets are limited at three levels, so a mistake cannot run up the whole bill.
- Four stacks start on their own from one repository.
- The chat app, the app builder, the MCP servers and the ingestion worker all connect to this base.
- One env file is the only place for secrets.
- A full backup is mostly a copy of one folder.
Known gaps
- I have no numbers for speed, memory use or answer quality.
- I do not publish what the model calls cost. The limits exist, but I do not share the figures.
- I have not described a tested restore. The page only says which data to back up.
- It runs for one household on one machine. I have not tested it with several users.
- The page does not say which licence the repository uses.
- I do not claim the setup is hardened beyond the local port binding and the key handling.