homebutler

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 →

See it run

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