Homebutler

HomeButler

Your tiny homelab butler. A single Go binary for running a small home server without babysitting it.

Website · Docs · Releases

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.

▶️ 34s demo — monitor, diagnose, and manage your homelab

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, and report baseline readiness
• 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
• 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, and whether report has a baseline for change detection.

📦 One-Command App Install

> homebutler install uptime-kuma — Deploy self-hosted apps in seconds. Pre-checks Docker, ports, and duplicates. Generates docker-compose.yml automatically. [See all available apps →](#app-install)

🗺️ Inventory & Topology

homebutler inventory scan
homebutler inventory export --format mermaid
homebutler --json inventory scan

inventory scan gives you a quick map of what is running on a server: system health, Docker containers, app ports, and system ports. Docker-published ports are connected back to the container that owns them, so local forwarding details like Colima/Lima stay understandable.

🏠 Home Network
   Server  homelab (192.168.1.10)
   Summary ✅ 1 running · ⚪ 1 stopped · 🌍 2 public ports · 🔒 4 local ports

📦 Containers (2)
   ├─ ⚪ vaultwarden · not started
   │  └─ image vaultwarden/server:latest
   └─ ✅ api-server · running
      ├─ image my-api:latest
      └─ exposes :8080 → 8080/tcp

🌐 App Ports (1)
   └─ 🌍 :8080/tcp · api-server

Use Mermaid export when you want a diagram for GitHub, Obsidian, docs, or an AI assistant:

graph TD
  home["🏠 Home Network"] --> homelab["🖥 homelab192.168.1.10"]
  homelab --> c1["📦 api-serverrunning"]
  homelab --> p1["🌍 :8080/tcpapi-server"]
  c1 -. exposes .-> p1

Demo

🌐 Web Dashboard

> homebutler serve — A real-time web dashboard embedded in the single binary via go:embed. Monitor all your servers, Docker containers, open ports, alerts, and Wake-on-LAN devices from any browser. Dark theme, auto-refresh every 5 seconds, fully responsive.

✨ Web Dashboard Highlights

• Server Overview — See all servers at a glance with color-coded status (green = online, red = offline)
• System Metrics — CPU, memory, disk usage with progress bars and color thresholds
• Docker Containers — Running/stopped status with friendly labels ("Running · 4d", "Stopped · 6h ago")
• Top Processes — Top processes sorted by CPU/memory with zombie detection
• Resource Warnings — Visual CPU, memory, and disk thresholds in the dashboard
• Network Ports — Open ports with process names and bind addresses
• Wake-on-LAN — One-click wake buttons for configured devices
• Server Switching — Dropdown to switch between local and remote servers
• Zero dependencies — No Node.js runtime needed. Frontend is compiled into the Go binary at build time

homebutler serve              # Start on port 8080
homebutler serve --port 3000  # Custom port
homebutler serve --demo       # Demo mode with realistic sample data

🔄 Process Restart Watch

Your container crashed at 3 AM — but why? homebutler watch catches it the moment it happens, saves the dying logs, figures out the cause, and tells you if it's happening over and over.

Supported backends: Docker (real-time event stream) · systemd (polling) · PM2 (polling)

Step 1: Add targets to watch

homebutler watch add nginx              # Interactive: choose Docker / systemd / PM2
homebutler watch add --kind docker nginx          # or specify directly
homebutler watch add --kind systemd nginx.service
homebutler watch add --kind pm2 my-api
homebutler watch list                   # See what you're watching

Step 2: Start monitoring

homebutler watch start                  # Foreground, Ctrl+C to stop
homebutler watch start --interval 10s   # Custom poll interval (default 30s)

When a crash is detected, you'll see:

[03:14:22] INCIDENT: nginx (incident nginx-20260410-031422.581-7a2124)
  Crash: OOM — process killed by SIGKILL (oom, confidence: high)
  ⚠ FLAPPING: acute (3 restarts in short window)

Step 3: Investigate

homebutler watch history                # List all incidents
homebutler watch show      # Full details

watch show output includes:

• Pre-death logs — what the process printed right before it died
• Post-restart logs — what happened after the restart
• Crash analysis — category (oom / panic / segfault / timeout / dependency / error), reason, confidence level, matched log patterns
• Flapping status — if the process is stuck in a crash loop

Crash Analysis

Every incident is automatically analyzed using exit codes and log patterns:

| Signal | Exit Code | Meaning | |--------|-----------|---------| | SIGKILL | 137 | OOM Killer or forced kill | | SIGSEGV | 139 | Segmentation fault (memory corruption) | | SIGTERM | 143 | Graceful shutdown request | | — | 1 | Application error | | — | 0 | Clean exit (may be intentional restart) |

Log patterns like panic:, Out of memory, Connection refused, FATAL, and timeout are matched automatically to help identify the root cause.

Flapping Detection

Detects when a process is stuck in a restart loop (e.g., crash → restart → crash again):

• Acute — 3+ restarts within 10 minutes (something is broken right now)
• Chronic — 5+ restarts within 24 hours (slow recurring issue)

Flapping incidents are tagged [FLAPPING] in history and highlighted in watch show.

Notifications (optional, off by default)

Notifications are disabled by default, which is useful for air-gapped or closed networks where everything runs locally.

A minimal example in ~/.config/homebutler/config.yaml:

notify:
  telegram:
    bot_token: "your-bot-token"
    chat_id: "your-chat-id"

watch:
  enabled: true
  notify_on: flapping
  cooldown: 5m
  flapping:
    short_window: 10m
    short_threshold: 3
    long_window: 24h
    long_threshold: 5

alerts:
  cpu: 90
  memory: 85
  disk: 90
  rules:
    - name: cpu-spike
      metric: cpu
      threshold: 90
      action: notify

Legacy ~/.homebutler/watch/config.json is still read as a fallback for watch-specific settings, and legacy alerts.yaml notify/webhook provider settings are still accepted for older setups.

• watch.enabled: true — allow watch notifications
• watch.notify_on: flapping — notify only when repeated restart loops are detected
• watch.notify_on: incident — notify on every incident
• watch.notify_on: all — notify on both incidents and flapping
• watch.notify_on: off — disable watch notifications without removing provider config
• watch.cooldown: 5m — suppress duplicate notifications for the same event fingerprint during the cooldown window
• watch.flapping — optional advanced tuning for restart-loop detection

Manage targets

homebutler watch remove nginx           # Stop watching
homebutler watch check                  # One-shot check (no continuous monitoring)

🖥️ TUI Dashboard

> homebutler watch tui — A terminal-based dashboard powered by Bubble Tea. Monitors all configured servers with real-time updates, color-coded resource bars, and Docker container status. No browser needed.

🧠 AI-Powered Management (MCP)

> Use natural language when you want automation. MCP clients can call homebutler tools to check server status, list Docker containers, inspect ports, or run operational workflows. [See screenshots & setup →](#mcp-server)

App Install

Deploy self-hosted apps with a single command. Each app runs via docker compose with automatic pre-checks, health verification, and clean lifecycle management.

# List available apps
homebutler install list

# Install (default port)
homebutler install uptime-kuma

# Install with custom port
homebutler install uptime-kuma --port 8080

# Install jellyfin with media directory
homebutler install jellyfin --media /mnt/movies

# Check status
homebutler install status uptime-kuma

# Stop (data preserved)
homebutler install uninstall uptime-kuma

# Stop + delete everything
homebutler install purge uptime-kuma

How it works

~/.homebutler/apps/
  └── uptime-kuma/
       ├── docker-compose.yml   ← auto-generated, editable
       └── data/                ← persistent data (bind mount)

• Pre-checks — Verifies docker is installed/running, port is available, no duplicate containers
• Compose-based — Each app gets its own docker-compose.yml you can inspect and customize
• Data safety — uninstall stops containers but keeps your data; purge removes everything
• Cross-platform — Auto-detects docker socket (default, colima, podman)

Available apps

| App | Default Port | Description | Notes | |-----|-------------|-------------|-------| | uptime-kuma | 3001 | Self-hosted monitoring tool | | | plex | 32400 | Plex Media Server | --media /path to mount media dir | | vaultwarden | 8080 | Bitwarden-compatible password manager | | | filebrowser | 8081 | Web-based file manager | | | it-tools | 8082 | Developer utilities (JSON, Base64, Hash, etc.) | | | gitea | 3002 | Lightweight self-hosted Git service | | | jellyfin | 8096 | Media system (movies, TV, music) | --media /path to mount media dir | | homepage | 3010 | Modern homelab dashboard | | | stirling-pdf | 8083 | All-in-one PDF tool (merge, split, convert, OCR) | | | speedtest-tracker | 8084 | Internet speed test with historical graphs | | | mealie | 9925 | Recipe manager and meal planner | | | pi-hole | 8088 | DNS ad blocking | ⚠️ Uses port 53 (DNS), NET_ADMIN capability | | adguard-home | 3000 | DNS ad blocker and privacy | ⚠️ Uses port 53 (DNS) | | portainer | 9443 | Docker management GUI | ⚠️ Mounts Docker socket (HTTPS) | | nginx-proxy-manager | 81 | Reverse proxy with SSL and web UI | ⚠️ Uses ports 80/443 |

App-specific options

# Jellyfin: mount your media library
homebutler install jellyfin --media /mnt/movies

# Pi-hole / AdGuard: DNS ad blocking (port 53 required)
homebutler install pi-hole
# ⚠️ If port 53 is in use (Linux): sudo systemctl disable --now systemd-resolved

# Portainer: Docker GUI (mounts docker socket)
homebutler install portainer
# Access via HTTPS: https://localhost:9443

# Nginx Proxy Manager: reverse proxy
homebutler install nginx-proxy-manager
# Default login: admin@example.com / changeme (change immediately!)

# Any app: custom port
homebutler install  --port 9999

Safety checks

• Port conflict detection — Checks if the port is already in use before install
• DNS mutual exclusion — Warns if pi-hole and adguard-home are both installed
• Docker socket warning — Alerts when an app requires Docker socket access (portainer)
• OS-specific guidance — Linux gets systemd-resolved fix, macOS gets lsof command
• Post-install tips — DNS setup, HTTPS access, default credential warnings

> Want more apps? Open an issue or see [Contributing](CONTRIBUTING.md).

Usage

homebutler  [flags]

Commands:
  status              System status (CPU, memory, disk, uptime)
  doctor              Diagnose health, exposure, backups, and readiness
  docker list         List running containers
  install        Install a self-hosted app (docker compose)
  alerts              Show current alert status
  watch tui           TUI dashboard (monitors all configured servers)
  watch add/list/remove  Manage watched containers
  watch check/start   One-shot or continuous restart detection
  watch history/show  Browse restart history
  serve               Web dashboard (browser-based, go:embed)

Flags:
  --json              JSON output (default: human-readable)
  --server      Run on a specific remote server
  --all               Run on all configured servers in parallel
  --port      Port for serve command (default: 8080)
  -

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Higangssh](https://github.com/Higangssh)
- **Source:** [Higangssh/homebutler](https://github.com/Higangssh/homebutler)
- **License:** MIT
- **Homepage:** https://homebutler.dev

Install and usage instructions live in the source repository linked above.