HomeButler

Manage your homelab from any AI — Claude, ChatGPT, Cursor, or 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.

<a href="https://www.youtube.com/watch?v=MFoDiYRH_nE"> <img src="assets/demo-thumbnail.png" alt="homebutler demo" width="800" /> </a> ▶️ Click to watch demo — Alert → Diagnose → Fix, all from chat (34s)

Why homebutler?

Other tools give you dashboards. homebutler gives you a conversation.

3 AM. Your server disk is 91% full. Here's what happens next:

Alert fires → you check logs from bed → AI restarts the problem container → disk drops to 66%. All from your phone. No SSH, no laptop, no dashboard login.

This is what homebutler + OpenClaw looks like in practice.

<details> <summary>📊 Comparison with alternatives</summary>

| | 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 | ~10MB, 0% idle | Medium | High | High |

</details>

Features

App Install — Deploy self-hosted apps with one command (uptime-kuma, vaultwarden, gitea, 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)
Alerts — Get notified when resources exceed thresholds
Backup & Restore — One-command Docker volume backup with compose + env files
MCP Server — Works with Claude Desktop, ChatGPT, Cursor, and any MCP client
Web Dashboard — Beautiful dark-themed web UI with homebutler serve
TUI Dashboard — Real-time terminal monitoring with homebutler watch (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.

<details> <summary>✨ Web Dashboard Highlights</summary>

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 10 processes sorted by CPU usage
Resource Alerts — Threshold-based warnings with visual progress bars (OK / WARNING / CRITICAL)
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

</details>

🖥️ TUI Dashboard

homebutler watch — 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 dashboard (all servers)
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

# 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 | |-----|-------------|-------------| | uptime-kuma | 3001 | Self-hosted monitoring tool | | 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 |

More apps coming soon. Want to add one? 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 dashboard (monitors all configured servers)
  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.

<details> <summary>📋 All Commands & Flags</summary>

Commands:
  init                Interactive setup wizard
  status              System status (CPU, memory, disk, uptime)
  watch               TUI dashboard (monitors all configured servers)
  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
  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
  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 compo

Homebutler

Install / Use

README