Repolode
Submit
Higangssh

Higangssh/homebutler

A single Go binary that remembers your server's last state and reports only the changes worth noticing, with an MCP server built in.

View on GitHubWebsite
Stars
315
Forks
22
Open issues
7
Last commit
7 days ago

What is it?

HomeButler is a homelab operations tool for Linux and macOS servers. Its `report` command saves a snapshot of containers, ports and disk usage, then compares each run against the previous snapshot and lists only what changed, such as a container recreated under the same name, a port taken over by another process, or a comparison that could not be made. Each change carries a fixed kind word, which is also present in its JSON output so scripts and agents can branch on it.

The project covers several areas: `doctor` runs read-only preflight checks for disk and memory pressure, stopped containers, public ports and missing backups; `watch` detects container, systemd and PM2 restarts, saves logs around each crash and flags restart loops; `backup drill` boots a backup archive in an isolated container and requires an HTTP health check to pass. It also installs a set of self-hosted apps through docker compose and can manage Proxmox VE endpoints over their API.

HomeButler is a single binary with no database and no resident agent on the machines it monitors; it connects over SSH when asked. It offers a CLI, a web dashboard, a terminal dashboard and an MCP server so AI agents can query the server without a full shell session.

Key features

  • 01Snapshot-based `report` that lists only changes since the last run, with JSON output
  • 02Read-only `doctor` checks for resource pressure, exposed ports, and backup hygiene
  • 03Restart detection for Docker, systemd and PM2 with saved logs and flapping alerts
  • 04`backup drill` boots backup archives in isolated containers and checks HTTP health
  • 05One-command installs for self-hosted apps via docker compose
  • 06Built-in MCP server, web dashboard and terminal dashboard

Use cases

  • Checking what changed on a home server after an update or restart
  • Verifying that backups can actually be restored before you need them
  • Letting an AI assistant inspect server state without giving it SSH shell access
  • Monitoring container restarts and crash loops on a small Linux or Raspberry Pi host

Quick start

  1. 1

    Install with Homebrew

    brew install Higangssh/homebutler/homebutler
  2. 2

    Run interactive setup to add your servers

    homebutler init
  3. 3

    Check current server status

    homebutler status
  4. 4

    Generate a health and change report

    homebutler report

Things to know

  • Requires Go 1.25+ if building from source.
  • Watching and reporting depend on Docker, systemd, or PM2 being available on the target machines.

In collections

Self-hosted uptime and server monitoringMCP serversSelf-hosted appsCLI & terminal tools

Topics

#homelab#monitoring#docker#self-hosted#devops#mcp#backup#cli#ai#change-detection

FAQ

What is homebutler?
A single Go binary that remembers your server's last state and reports only the changes worth noticing, with an MCP server built in. HomeButler is a homelab operations tool for Linux and macOS servers. Its `report` command saves a snapshot of containers, ports and disk usage, then compares each run against the previous snapshot and lists only what changed, such as a container recreated under the same name, a port taken over by another process, or a comparison that could not be made. Each change carries a fixed kind word, which is also present in its JSON output so scripts and agents can branch on it.
Is homebutler free to use? What license does it have?
homebutler is open source under the MIT license. Check the license terms before using it in commercial products.
Is homebutler still maintained?
Actively maintained. The last commit to homebutler was on Nov 1, 2026.
What can I use homebutler for?
Checking what changed on a home server after an update or restart Verifying that backups can actually be restored before you need them Letting an AI assistant inspect server state without giving it SSH shell access Monitoring container restarts and crash loops on a small Linux or Raspberry Pi host
How do I install homebutler?
Install with Homebrew: brew install Higangssh/homebutler/homebutler Run interactive setup to add your servers: homebutler init Check current server status: homebutler status Generate a health and change report: homebutler report
Where can I get homebutler?
The source code and installation instructions are on GitHub: https://github.com/Higangssh/homebutler

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects