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 line 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 →

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. No always-on web service. Just one Go binary you can use from the terminal, scripts, a web dashboard, or AI tools.

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.

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

# Interactive setup — add your servers in seconds
homebutler init

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 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.

HomeButler is a small operations toolkit for that messy middle.

Why not just use Portainer, Netdata, or CasaOS?

Those are great dashboards. HomeButler is CLI-first, scriptable, JSON-friendly, air-gap friendly, and safe to copy onto any server. Use it when you want commands you can run from a terminal, cron job, SSH session, CI script, or AI agent — especially when you care more about “what changed?” than another graph.

Core workflows

🧾 Butler 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.

🩺 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.

🗂 Config Validation

homebutler config validate
homebutler config validate --strict   # exit non-zero on warnings too
homebutler config validate --json

config validate reads your config without starting anything and tells you which file was used, which of the four resolution rules picked it, and what homebutler actually made of each section. It exists because the two ways config goes wrong are both silent: a key homebutler does not recognise is dropped without a word, and a --config path that does not exist falls back to built-in defaults rather than failing.

Sections
   ✓ servers     2 servers (homelab, nas)
   · notify      not set
   ✓ alerts      cpu 95% · memory 85% · disk 90%

Findings
   ⚠️ Line 5: field notifiy not found in the homebutler config
      → Did you mean "notify"? Unrecognised keys are ignored silently.

📦 One-Command App Install

**`h