# Homebutler > 🏠 Manage your homelab from chat. Single binary, zero dependencies. - **Type:** MCP server - **Install:** `agentstack add mcp-higangssh-homebutler` - **Verified:** Pending review - **Seller:** [Higangssh](https://agentstack.voostack.com/s/higangssh) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Higangssh](https://github.com/Higangssh) - **Source:** https://github.com/Higangssh/homebutler - **Website:** https://homebutler.dev ## Install ```sh agentstack add mcp-higangssh-homebutler ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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 ```bash # 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: ```bash 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: ```bash 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 ```bash 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 ```bash 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 ```bash 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. ```text 🏠 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: ```mermaid 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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`: ```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 ```bash 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. ```bash # 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 ```bash # 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](https://github.com/Higangssh/homebutler/issues) 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. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: flagged β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-higangssh-homebutler - Seller: https://agentstack.voostack.com/s/higangssh - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.