HomeButler is an operations status reporting tool designed for Homelab multi-server environments, distributed as a single Go binary. Its core idea is not to display current real-time charts, but to remember the last state of the servers and determine which changes are worth telling the user or an AI agent about.
Main capabilities
Change detection and reporting: HomeButler saves snapshots and compares them with the most recent snapshot on subsequent runs. Each line of change contains three pieces of information: the change type, the change target, and the specific change content. Types use a fixed vocabulary and remain consistent in --json output, making them easy for machines to parse. Among these, replaced indicates a case where a container with the same name was recreated but its various counts are unchanged, which is an important change that count comparison methods cannot detect; skipped indicates that comparison was not possible, rather than reporting that there was no change. The report header notes the snapshots being compared, avoiding ambiguity about the time window.
System and container monitoring: Remotely checks servers via SSH, showing system health, Docker containers, application ports, and system ports. Docker-published ports are linked back to the container they belong to. inventory scan provides a quick inventory, and --filter can be used to show only ports open to all interfaces.
Process restart monitoring and crash analysis: The watch feature supports Docker, systemd, and PM2 backends. Docker uses a real-time event stream, while systemd and PM2 use polling. When a crash is detected, it saves pre-death logs and post-restart logs, and analyzes the cause classification based on exit codes and log patterns, such as oom, panic, segfault, timeout, dependency, error, while also identifying flapping restart loops (acute: more than 3 times within 10 minutes; chronic: more than 5 times within 24 hours).
Backup verification: backup drill starts the backup archive in an isolated container with a separate network and ports, and requires passing an HTTP health check to be considered successful. On failure, it returns a non-zero exit code, so it can be placed in cron for regular execution.
doctor precheck: Read-only checks for common issues, including excessively high disk or memory usage, stopped containers, publicly bound ports, expired or missing backups, missing notifications, whether the reporting baseline is ready, whether the configured Proxmox endpoint is reachable, etc. Each finding provides a suggested next-step command.
Configuration validation: config validate reads the configuration without starting any service, reports which file was used, which of the four parsing rules selected it, and the parsing result for each configuration section, avoiding unknown keys being silently dropped or silently falling back to default values when a path does not exist.
One-click application installation: homebutler install can deploy self-hosted applications such as Uptime Kuma, Jellyfin, Pi-hole, Gitea, and Portainer, automatically pre-checks Docker, ports, and duplicates, and generates docker-compose.yml.
Web dashboard: homebutler serve starts a web interface embedded in the binary, allowing you to view servers, Docker containers, open ports, alerts, and Wake-on-LAN, and supports editing configuration with --token. The frontend is compiled into the Go binary at build time, with no need for Node.js.
Proxmox support: can view nodes, QEMU and LXC guests, storage, and task status, and perform power operations on guests.
MCP integration: includes a built-in MCP server, allowing AI assistants to inspect servers through a structured interface without needing to provide a full SSH shell.
Usage
Can be run via CLI, cron, the web dashboard, or an AI agent. Supports running as a container and accessing target machines via SSH:
docker run -v ~/.config/homebutler:/config -v ~/.ssh:/root/.ssh:ro ghcr.io/higangssh/homebutler
Machine-readable JSON output is available everywhere. watch install can install the monitoring loop as a Linux systemd user unit or macOS launchd agent, so that it continues running after logout and restart.
Suitable scenarios
Suitable for Homelab users who need to maintain multiple self-hosted servers, especially those who want to quickly understand server changes, troubleshoot why services restarted in the early morning, verify backup recoverability, and let AI assistants inspect servers in a structured way without exposing SSH. It can also be used alongside tools such as Uptime Kuma, Beszel, Netdata, and Dozzle.
Limitations and notes
JudgmentThe rules are written rules rather than a model; the same input produces the same report, with no need for AI, an account, or a paid tier, but the material does not state whether a paid version exists. No agent or daemon runs on the monitored machines; the binary is deployed once via homebutler deploy and runs only when requested over SSH. Notifications are disabled by default, making it suitable for isolated or closed networks. systemd restart requires root or a polkit rule, and unprivileged execution will be rejected. Targets in a flapping state will not be restarted. For specific installation and configuration details, refer to the official documentation and release page.
