homebutler

homebutler is a single Go binary that remembers what your server looked like last time and tells you what moved: a container recreated under the same name, a port answered by a different process, a backup that no longer restores. It reports to a person through the CLI, a terminal dashboard, or a web dashboard, and to an agent through MCP or JSON.

── Notable Changes ───────────────────────────────────────────
   replaced  hb-demo  recreated, 00702cacc7d4 → 11dada014233

A report that only compares counts sees the same number of containers before and after and calls it "no change." homebutler names the container that was swapped out.

Quickstart

Install homebutler, take a baseline, and read your first report.

Connect your agent

Give Claude, Cursor, or any MCP client typed answers instead of an SSH shell.

Report

What earns a line in a report, and what is left out on purpose.

Backup drill

Boot a backup in its own container and check that the app answers.

What it does

• Reports what changed. report compares the server with the last snapshot and labels each change with one of eight kinds, such as replaced, port or gone.
• Diagnoses common problems. doctor checks disk and memory pressure, stopped containers, ports open on every interface, and backups that are missing or never tested. Each finding names the command to run next.
• Catches crashes. watch saves the logs from before and after a restart, classifies the cause (OOM, panic, segfault), and detects restart loops.
• Proves backups restore. backup drill boots an archive as a second copy of the app and requires an HTTP health check to pass.
• Installs apps. install deploys 15 self-hosted apps, such as Uptime Kuma, Jellyfin, and Pi-hole, with a generated docker-compose.yml.
• Reaches more than one machine. Multi-server runs the commands that take --server on remote servers over SSH, and Proxmox VE endpoints are read through the Proxmox API.

The ways in

Interface	Start it with	Use it for
CLI	homebutler <command>	Terminal, scripts and cron. Add --json for machine-readable output.
MCP server	homebutler mcp	Claude Desktop, Claude Code, Cursor and other MCP clients.
Web dashboard	homebutler serve	A browser view of servers, containers, ports and the report, on port 8080.
TUI dashboard	homebutler watch tui	A live terminal view of every configured server.

All four call the same code, so a person and an agent get the same answer. homebutler runs no daemon and keeps no database: it runs when you call it, and stores snapshots, incidents and backups as files under ~/.homebutler/.

Next steps

Installation

Homebrew, the install script, Go, npm, a container, or a source build.

How it works

Snapshots, the four interfaces, and how homebutler reaches other machines.