GitHub - Higangssh/homebutler: 🏠 Manage your homelab from chat. Single binary, zero dependencies.

Website · Docs · Releases

Manage your homelab from chat, AI tools, or the terminal. One binary. Zero dependencies.

A single-binary CLI + MCP server that lets you monitor servers, control Docker, wake machines, and scan your network — from chat, AI tools, or the command line.

▶️ Click to watch demo — monitor, diagnose, and manage from chat (34s)

Why homebutler?

Other tools give you dashboards. homebutler gives you a tool layer you can use from chat, AI tools, or the terminal.

The clearest story in homebutler today is watch:

• detect service restarts
• capture crash evidence
• spot flapping loops
• review incidents later

That makes it useful both as a normal CLI and as the execution layer under tools like OpenClaw.

Features

• App Install — Deploy 15 self-hosted apps with one command (uptime-kuma, jellyfin, pi-hole, and more)
• System Status — CPU, memory, disk, uptime at a glance
• Docker Management — List, restart, stop, logs for containers
• Multi-server — Manage remote servers over SSH (key & password auth)
• Notifications — Multi-channel notifications via Telegram, Slack, Discord, or generic webhook
• Backup & Restore — One-command Docker volume backup with compose + env files
• Backup Drill — Verify backups actually work by booting them in isolated containers
• MCP Server — Works with Claude Desktop, ChatGPT, Cursor, and any MCP client
• Web Dashboard — Beautiful dark-themed web UI with homebutler serve
• Watch & History — Track restarts for Docker containers, systemd services, and PM2 apps; capture pre-death and post-restart logs; browse restart history (homebutler watch)
• TUI Dashboard — Real-time terminal monitoring with homebutler watch tui (btop-style)
• Wake-on-LAN — Power on machines remotely
• Port Scanner — See what's listening and which process owns it
• Network Scan — Discover devices on your LAN
• JSON Output — Pipe-friendly, perfect for AI assistants to parse

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

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.

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 <incident-id>     # 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:

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)

One natural language prompt manages your entire homelab. Claude Code calls homebutler MCP tools in parallel — checking server status, listing Docker containers, and alerting on disk usage across multiple servers. See screenshots & setup →

Quick Start

# One-line install (recommended, auto-detects OS/arch)
curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh

# Or via Homebrew
brew install Higangssh/homebutler/homebutler

# Or via npm (MCP server only)
npm install -g homebutler

# Interactive setup — adds your servers in seconds
homebutler init

# Run
homebutler status
homebutler watch tui         # TUI dashboard (all servers)
homebutler watch start       # Process restart monitor (Docker/systemd/PM2)
homebutler serve             # Web dashboard at http://localhost:8080
homebutler docker list
homebutler wake desktop
homebutler ports
homebutler status --all

# Install a self-hosted app (e.g. Uptime Kuma monitoring)
homebutler install uptime-kuma

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

Usage

homebutler <command> [flags]

Commands:
  status              System status (CPU, memory, disk, uptime)
  docker list         List running containers
  install <app>       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 <name>     Run on a specific remote server
  --all               Run on all configured servers in parallel
  --port <number>     Port for serve command (default: 8080)
  --config <path>     Config file (auto-detected, see Configuration)

Run homebutler --help for all commands.

Commands:
  init                Interactive setup wizard
  status              System status (CPU, memory, disk, uptime)
  watch tui           TUI dashboard (monitors all configured servers)
  watch add <name>    Add container to restart watch list
  watch list          Show watched containers
  watch remove <name> Remove container from watch list
  watch check         One-shot restart check
  watch start         Continuous restart monitoring loop
  watch history       List restart history (alias: incidents)
  watch show <id>     Show restart details with logs
  serve               Web dashboard (browser-based, go:embed)
  docker list         List running containers
  docker restart <n>  Restart a container
  docker stop <n>     Stop a container
  docker logs <n>     Show container logs
  wake <name>         Send Wake-on-LAN packet
  ports               List open ports with process info
  ps                  Show top processes (alias: processes)
  ps --sort mem       Sort by memory instead of CPU
  ps --limit 20       Show top 20 (default: 10, 0 = all)
  network scan        Discover devices on LAN
  alerts              Show current alert status
  alerts --watch      Continuous monitoring with real-time alerts
  trust <server>      Register SSH host key (TOFU)
  backup              Backup Docker volumes, compose files, and env
  backup list         List existing backups
  backup drill <app>  Verify backup restores correctly (isolated)
  backup drill --all  Verify all apps in backup
  restore <archive>   Restore from a backup archive
  upgrade             Upgrade local + all remote servers to latest
  deploy              Install homebutler on remote servers
  install <app>       Install a self-hosted app (docker compose)
  install list        List available apps
  install status <a>  Check installed app status
  install uninstall   Stop app (keep data)
  install purge       Stop app + delete all data
  mcp                 Start MCP server (JSON-RPC over stdio)
  version             Print version

Flags:
  --json              JSON output (default: human-readable)
  --server <name>     Run on a specific remote server
  --all               Run on all configured servers in parallel
  --port <number>     Port for serve command (default: 8080)
  --demo              Run serve with realistic demo data
  --watch             Continuous monitoring mode (alerts command)
  --interval <dur>    Watch interval, e.g. 30s, 1m (default: 30s)
  --config <path>     Config file (auto-detected, see Configuration)
  --local             Upgrade only the local binary (skip remote servers)
  --local <path>      Use local binary for deploy (air-gapped)
  --service <name>    Target a specific Docker service (backup/restore)
  --to <path>         Custom backup destination directory
  --archive <path>    Specific backup archive for drill
  --all               Verify all supported apps (backup drill)

homebutler serve                # http://localhost:8080
homebutler serve --port 3000    # custom port
homebutler serve --demo         # demo mode with sample data

Monitoring

homebutler watch is the main monitoring workflow. It focuses on restart detection, crash analysis, flapping detection, and incident history.

# Target management
homebutler watch add nginx                  # interactive kind selection
homebutler watch add --kind docker nginx    # explicit kind
homebutler watch list                       # show watched targets
homebutler watch remove nginx               # remove a target

# Monitoring
homebutler watch start                      # start continuous crash/restart monitoring
homebutler watch start --interval 10s       # custom poll interval for polling-based backends
homebutler watch check                      # one-shot restart check

# Investigation
homebutler watch history                    # incident history
homebutler watch show <incident-id>         # incident details + logs
homebutler watch tui                        # TUI dashboard

# Notifications
homebutler notify test                      # test configured notification providers

If you only learn one monitoring workflow in homebutler, learn watch first.

Backup & Restore

One-command Docker backup — volumes, compose files, and env variables.

homebutler backup                          # backup everything
homebutler backup --service jellyfin       # specific service
homebutler backup --to /mnt/nas/backups/   # custom destination
homebutler backup list                     # list backups
homebutler restore ./backup.tar.gz         # restore

⚠️ Database services should be paused before backup for data consistency.

📖 Full backup documentation → — how it works, archive structure, security notes.

Alert Thresholds (Advanced)

alerts still exists for CPU, memory, and disk threshold checks, but it is an advanced flow and not the recommended first step for new users.

homebutler alerts --watch                  # default: 30s interval
homebutler alerts --watch --interval 10s   # check every 10 seconds
homebutler alerts history                  # view alert history
homebutler notify test                     # test your notification channels

Default thresholds: CPU 90%, Memory 85%, Disk 90%. Start with watch, then add alerts only if you specifically want threshold-based checks.

🔍 Backup Drill

"Having a backup" and "being able to restore" are different things.

Backup Drill boots your backup in an isolated Docker environment and verifies the app actually responds — like a fire drill for your data.

homebutler backup drill uptime-kuma        # verify one app
homebutler backup drill --all              # verify all apps
homebutler backup drill --json             # machine-readable output
homebutler backup drill --archive ./file   # use a specific backup

What happens:

1. Finds the latest backup archive
2. Verifies archive integrity (tar validation)
3. Creates an isolated Docker network + random port
4. Boots the app from backup data
5. Runs an HTTP health check
6. Reports pass/fail and cleans up everything

🔍 Backup Drill — uptime-kuma

  📦 Backup: ~/.homebutler/backups/backup_2026-04-04_1711.tar.gz
  📏 Size: 18.6 MB
  🔐 Integrity: ✅ tar valid (8 files)

  🚀 Boot: ✅ container started in 0s
  🌐 Health: ✅ HTTP 200 on port 58574
  ⏱️  Total: 2s

  ✅ DRILL PASSED

Zero risk — runs in a completely isolated environment. Your running services are never touched.

Supports health checks for: nginx-proxy-manager, vaultwarden, uptime-kuma, pi-hole, gitea, jellyfin, plex, portainer, homepage, adguard-home.

Configuration

homebutler init    # interactive setup wizard

📖 Configuration details → — config file locations, watch/notify options, and advanced alert thresholds.

Multi-server

Manage multiple servers from a single machine over SSH.

homebutler status --server rpi     # query specific server
homebutler status --all            # query all in parallel
homebutler deploy --server rpi     # install on remote server
homebutler upgrade                 # upgrade all servers

📖 Multi-server setup → — SSH auth, config examples, deploy & upgrade.

MCP Server

Built-in MCP server — manage your homelab from any AI tool with natural language.

{
  "mcpServers": {
    "homebutler": {
      "command": "npx",
      "args": ["-y", "homebutler@latest"]
    }
  }
}

Works with Claude Desktop, ChatGPT, Cursor, Windsurf, and any MCP client.

📖 MCP server setup → — supported clients, available tools, agent skills.

Installation

Homebrew (Recommended)

brew install Higangssh/homebutler/homebutler

Automatically installs to PATH. Works on macOS and Linux.

One-line Install

curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh

Auto-detects OS/architecture, downloads the latest release, and installs to PATH.

npm (MCP server)

npm install -g homebutler

Downloads the Go binary automatically. Use npx -y homebutler@latest to run without installing globally.

Go Install

go install github.com/Higangssh/homebutler@latest

Build from Source

git clone https://github.com/Higangssh/homebutler.git
cd homebutler
make build

Uninstall

rm $(which homebutler)           # Remove binary
rm -rf ~/.config/homebutler      # Remove config (optional)

Architecture

Goal: Engineers manage servers from chat — not SSH.

Alert fires → AI diagnoses → AI fixes → you get a summary on your phone.

homebutler is the tool layer in an AI ChatOps stack. It doesn't care what's above it — use any chat platform, any AI agent, or just your terminal.

┌──────────────────────────────────────────────────┐
│  Layer 3 — Chat Interface                        │
│  Telegram · Slack · Discord · Terminal · Browser │
│  (Your choice — homebutler doesn't touch this)   │
└──────────────────────┬───────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────┐
│  Layer 2 — AI Agent                              │
│  OpenClaw · LangChain · n8n · Claude Desktop     │
│  (Understands intent → calls the right tool)     │
└──────────────────────┬───────────────────────────┘
                       │  CLI exec or MCP (stdio)
┌──────────────────────▼───────────────────────────┐
│  Layer 1 — Tool (homebutler)       ← YOU ARE HERE │
│                                                   │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │   CLI   │  │   MCP   │  │   Web   │           │
│  │ stdout  │  │  stdio  │  │  :8080  │           │
│  └────┬────┘  └────┬────┘  └────┬────┘           │
│       └────────────┼────────────┘                 │
│                    ▼                              │
│             internal/*                            │
│   system · docker · ports · network               │
│   wake · alerts · remote (SSH)                    │
└───────────────────────────────────────────────────┘

Three interfaces, one core:

All three call the same internal/ packages — no code duplication.

homebutler is Layer 1. Swap Layer 2 and 3 to fit your stack:

• Terminal only → homebutler status (no agent needed)
• Claude Desktop → MCP server, Claude calls tools directly
• OpenClaw + Telegram → Agent runs CLI commands from chat
• Custom Python bot → subprocess.run(["homebutler", "status", "--json"])
• n8n / Dify → Execute node calling homebutler CLI

No ports opened by default. CLI and MCP use stdin/stdout only. The web dashboard is opt-in (homebutler serve, binds 127.0.0.1).

Now: CLI + MCP + Web dashboard — you ask, it answers.

Goal: Full AI ChatOps — infrastructure that manages itself.

Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change.

License

MIT