Higangssh/homebutler

Only the changes worth mentioning.
A single Go binary that remembers what your server looked like last time,
and tells you — or an agent — what moved.
Website ·
Docs ·
Releases
A real run of it on a Raspberry Pi is under Butler Report .
Or as a container, reaching your machines over SSH — docs/docker.md:
docker run -v ~/.config/homebutler:/config -v ~/.ssh:/root/.ssh:ro ghcr.io/higangssh/homebutler
Section rules, labels, and severities are colour-coded in a terminal. Colour is
dropped automatically when output is piped, redirected, or run from cron.
That is the whole idea. Most homelab tools show you a graph of right now, and leave
"does this matter?" to you. HomeButler remembers what your server looked like last
time, decides what is worth saying, and says it — six containers before and six after
is not "no change" when one of them is a different container.
Reading a change
Every change line, like those in the card at the top, is three columns: **what kind of change**, **what it happened to**, and
**what exactly happened**. The kind is one of eight words, and it is the same word in
--json, so an agent branches on it without reading prose:
| Kind | Means | You would see it after |
| --- | --- | --- |
| gone | it was there last time and is not now | docker rm, a service stopping, a port closing |
| new | it was not there last time and is now | starting anything |
| replaced | same name, different thing underneath | docker compose up -d — the container is recreated, so the name and the count are unchanged |
| image | same container, different image | pulling a new tag |
| state | same container, running where it was stopped, or the reverse | a crash, or bringing something back up |
| port | same port, a different process answering on it | one service taking over another's port |
| disk | a mount moved by more than half a gigabyte | anything that writes |
| skipped | the comparison could not be made | Docker was down when either snapshot was taken |
replaced is the one the rest of this exists for. A container recreated under the
same name leaves every count identical, which is why a report that compares counts —
as this one did before 0.26.0 — answers "no significant changes" while the thing you
were running has been swapped out underneath you.
skipped is the second: homebutler says it could not compare rather than reporting
nothing changed. An all-clear it cannot stand behind is worse than no answer.
The header names the snapshot being compared against, so "what changed" is never
ambiguous about the window it covers.
📖 **What earns a line, and what is deliberately suppressed →**
HomeButler helps you answer the boring but painful questions every homelab eventually creates:
- What is running on my server right now?
- Which container owns this port?
- Why did this service restart at 3 AM?
- Is my backup actually restorable?
- Can I install this self-hosted app without hand-writing another compose file?
- Can I let an AI assistant inspect my server without handing it a full SSH shell?
No daemon required, no database. Run it from a terminal, cron, a web dashboard you start when you want one, or an AI agent.
The design goal is simple: give humans and agents a narrow, structured interface to the server. HomeButler returns readable summaries and JSON instead of asking you to trust a black-box shell session.
The whole thing in half a minute · watch it full size
Quick Start
Use it right away:
Machine-readable output is available everywhere:
What it does
- **Install apps** — deploy Uptime Kuma, Jellyfin, Pi-hole, Gitea, Portainer, and more with one command
- **Map your server** — see containers, exposed ports, system ports, and service topology
- **Run a doctor check** — diagnose resource pressure, stopped containers, public ports, backup hygiene, notifications, report baseline readiness, and configured Proxmox endpoint reachability
- **Catch crashes** — save logs before/after Docker, systemd, or PM2 restarts and detect flapping loops
- **Verify backups** — boot backups in isolated containers before you trust them
- **See a Proxmox cluster** — nodes, QEMU and LXC guests, storage, task status, and honest dashboard freshness, with power actions that name their target explicitly
- **Use it anywhere** — CLI, JSON, web dashboard, or MCP for AI agents without giving them SSH
Why homebutler?
Self-hosting is not hard because one docker compose up is hard. It is hard because the maintenance never ends: ports collide, containers restart silently, backups look fine until restore day, and every server becomes a slightly different snowflake.