HomeButler

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.

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.

| | homebutler | Glances/btop | Netdata | CasaOS | |---|---|---|---|---| | TUI dashboard | ✅ Built-in | ✅ | ❌ Web | ❌ Web | | Web dashboard | ✅ Embedded | ❌ | ✅ | ✅ | | Single binary | ✅ | ❌ | ❌ | ❌ | | Optional web server | ✅ On-demand | Always-on | Always-on | Always-on | | Multi-server SSH | ✅ Parallel | ❌ | ❌ | ❌ | | MCP support | ✅ Built-in | ❌ | ❌ | ❌ | | Chat integration | ✅ Native | ❌ | ❌ | ❌ | | AI-friendly JSON | ✅ | ❌ | ⚠️ API | ⚠️ API | | Docker control | ✅ | ⚠️ Monitor | ❌ | ✅ | | Wake-on-LAN | ✅ | ❌ | ❌ | ❌ | | Network scan | ✅ | ❌ | ❌ | ❌ | | Remote deploy | ✅ One command | ❌ | ❌ | ❌ | | Air-gapped install | ✅ Copy binary | ⚠️ apt/brew | ❌ Docker | ❌ Docker | | Resource usage | Low single-binary footprint | Medium | High | High |

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.

• 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 <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:

| 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 w