Homebutler

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

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 report

homebutler report

homebutler report --keep 7 # retain only the latest 7 snapshots homebutler report --no-save # preview without writing a snapshot

report gives you a concise butler-style summary of your homelab: current health, warnings, notable changes since the previous snapshot, and suggested next commands. On the first run, HomeButler creates a baseline under ~/.homebutler/reports/snapshots/; later runs compare against the latest snapshot. Old snapshots are pruned automatically (--keep 30 by default) so reports do not grow forever.

Section rules, labels, and severities are colour-coded in a terminal. Colour is dropped automatically when output is piped, redirected, or run from cron.

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:

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 →](docs/report.md)

See it run

The whole thing in half a minute · watch it full size

Why homebutler?

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.

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.

HomeButler is a small operations toolkit for that messy middle.

Alongside what you already run

Keep Uptime Kuma for *is it up*, Beszel or Netdata for *the graph*, Dozzle for *the logs*. HomeButler answers the question none of them ask: what is different from last time, and does it matter?

• No agent on the machines it watches. The binary is put there once with homebutler deploy and runs only when asked, over SSH — no daemon, no open port, nothing listening between runs.
• The judgement is a written rule, not a model. What earns a line is in docs/report.md, and the same input gives the same report — no AI required, no account, no paid tier.
• It checks that a backup comes back. A backup you have never restored is a folder. backup drill boots the archive as a second copy of the app, on a network and port of its own, and requires it to answer an HTTP health check before calling the archive good — then removes everything it made. A failed drill exits non-zero, so backup drill --all belongs in the same cron entry as backup. docs/backup.md has what it does and what it does not prove.

  🔐 Integrity: ✅ tar valid (8 files)

🚀 Boot: ✅ container started in 0s 🌐 Health: ✅ HTTP 200 on port 60405

✅ DRILL PASSED

Quick Start

# One-line install (auto-detects OS/arch)

curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh

Or via Homebrew

brew install Higangssh/homebutler/homebutler

Or as a container — the hub that reaches your machines over SSH

docker run -d -p 8080:8080 -v ~/.config/homebutler:/config -v ~/.ssh:/root/.ssh:ro \ ghcr.io/higangssh/homebutler serve --host 0.0.0.0 --token "$(openssl rand -hex 16)"

Interactive setup — add your servers in seconds

homebutler init

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

Use it right away:

homebutler status                    # CPU, memory, disk, uptime

homebutler docker list # running containers homebutler inventory scan # containers + ports + topology homebutler report # butler-style health report + change summary homebutler install uptime-kuma # deploy a self-hosted app homebutler backup drill uptime-kuma # verify a backup actually restores homebutler watch tui # terminal dashboard homebutler serve # web dashboard at http://localhost:8080

Machine-readable output is available everywhere:

homebutler status --json

homebutler inventory scan --json homebutler report --json

What else 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

🩺 Doctor Check

homebutler doctor

homebutler doctor --strict # non-zero exit if warnings/failures are found homebutler doctor --json # automation / MCP friendly

doctor is a read-only preflight for the problems homelab users usually discover too late: high disk or memory usage, stopped containers, public bind ports, stale or missing backups, missing notifications, whether report has a baseline for change detection, and whether each configured Proxmox endpoint is reachable with the token it has. Every finding names the next command to run, so --strict makes it usable from cron or CI — including a Proxmox host that is unreachable or rebooting.

Every finding carries a category, and --json carries the same word, so a caller filters on it without reading the title:

| incomplete | a collector did not answer, so this dia