{"id":47464607,"url":"https://github.com/Higangssh/homebutler","last_synced_at":"2026-04-08T00:00:46.235Z","repository":{"id":340114772,"uuid":"1164599765","full_name":"Higangssh/homebutler","owner":"Higangssh","description":"🏠 Manage your homelab from chat. Single binary, zero dependencies.","archived":false,"fork":false,"pushed_at":"2026-04-01T08:36:37.000Z","size":102849,"stargazers_count":81,"open_issues_count":7,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-03T03:20:13.337Z","etag":null,"topics":["ai","chatops","cli","devops","docker","go","golang","homelab","mcp","mcp-server","monitoring","openclaw","raspberry-pi","selfhosted","ssh","wake-on-lan"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Higangssh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T09:17:24.000Z","updated_at":"2026-04-01T13:20:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Higangssh/homebutler","commit_stats":null,"previous_names":["higangssh/homebutler"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/Higangssh/homebutler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Higangssh%2Fhomebutler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Higangssh%2Fhomebutler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Higangssh%2Fhomebutler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Higangssh%2Fhomebutler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Higangssh","download_url":"https://codeload.github.com/Higangssh/homebutler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Higangssh%2Fhomebutler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31533824,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","chatops","cli","devops","docker","go","golang","homelab","mcp","mcp-server","monitoring","openclaw","raspberry-pi","selfhosted","ssh","wake-on-lan"],"created_at":"2026-03-24T15:00:23.571Z","updated_at":"2026-04-08T00:00:46.222Z","avatar_url":"https://github.com/Higangssh.png","language":"Go","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"HomeButler\" width=\"160\"\u003e\n\u003c/p\u003e\n\n# HomeButler\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://homebutler.dev\"\u003eWebsite\u003c/a\u003e · \u003ca href=\"https://github.com/Higangssh/homebutler#readme\"\u003eDocs\u003c/a\u003e · \u003ca href=\"https://github.com/Higangssh/homebutler/releases\"\u003eReleases\u003c/a\u003e\n\u003c/p\u003e\n\n**Manage your homelab from any AI — Claude, ChatGPT, Cursor, or terminal. One binary. Zero dependencies.**\n\n[![Go](https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go\u0026logoColor=white)](https://go.dev)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Higangssh/homebutler)](https://goreportcard.com/report/github.com/Higangssh/homebutler)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/Higangssh/homebutler)](https://github.com/Higangssh/homebutler/releases)\n[![homebutler MCP server](https://glama.ai/mcp/servers/Higangssh/homebutler/badges/score.svg)](https://glama.ai/mcp/servers/Higangssh/homebutler)\n\nA 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.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=MFoDiYRH_nE\"\u003e\n    \u003cimg src=\"assets/demo-thumbnail.png\" alt=\"homebutler demo\" width=\"800\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003e▶️ Click to watch demo — Alert → Diagnose → Fix, all from chat (34s)\u003c/em\u003e\u003c/p\u003e\n\n## Why homebutler?\n\n\u003e Other tools give you dashboards. homebutler gives you a **conversation**.\n\n**3 AM. Your server disk is 91% full. Here's what happens next:**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo-chat.png\" alt=\"HomeButler alert → diagnose → fix via Telegram\" width=\"480\" /\u003e\n\u003c/p\u003e\n\nAlert 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.\n\nThis is what homebutler + [OpenClaw](https://github.com/openclaw/openclaw) looks like in practice.\n\n\u003cdetails\u003e\n\u003csummary\u003e📊 Comparison with alternatives\u003c/summary\u003e\n\n| | homebutler | Glances/btop | Netdata | CasaOS |\n|---|---|---|---|---|\n| TUI dashboard | ✅ Built-in | ✅ | ❌ Web | ❌ Web |\n| Web dashboard | ✅ Embedded | ❌ | ✅ | ✅ |\n| Single binary | ✅ | ❌ | ❌ | ❌ |\n| Optional web server | ✅ On-demand | Always-on | Always-on | Always-on |\n| Multi-server SSH | ✅ Parallel | ❌ | ❌ | ❌ |\n| MCP support | ✅ Built-in | ❌ | ❌ | ❌ |\n| Chat integration | ✅ Native | ❌ | ❌ | ❌ |\n| AI-friendly JSON | ✅ | ❌ | ⚠️ API | ⚠️ API |\n| Docker control | ✅ | ⚠️ Monitor | ❌ | ✅ |\n| Wake-on-LAN | ✅ | ❌ | ❌ | ❌ |\n| Network scan | ✅ | ❌ | ❌ | ❌ |\n| Remote deploy | ✅ One command | ❌ | ❌ | ❌ |\n| Air-gapped install | ✅ Copy binary | ⚠️ apt/brew | ❌ Docker | ❌ Docker |\n| Resource usage | ~10MB, 0% idle | Medium | High | High |\n\n\u003c/details\u003e\n\n## Features\n\n- **App Install** — Deploy 15 self-hosted apps with one command (`uptime-kuma`, `jellyfin`, `pi-hole`, and more)\n- **System Status** — CPU, memory, disk, uptime at a glance\n- **Docker Management** — List, restart, stop, logs for containers\n- **Multi-server** — Manage remote servers over SSH (key \u0026 password auth)\n- **Self-Healing** — YAML-defined rules that auto-detect and auto-fix issues (restart containers, prune disk, run scripts)\n- **Alerts \u0026 Notifications** — Multi-channel alerts via Telegram, Slack, Discord, or generic webhook\n- **Backup \u0026 Restore** — One-command Docker volume backup with compose + env files\n- **Backup Drill** — Verify backups actually work by booting them in isolated containers\n- **MCP Server** — Works with Claude Desktop, ChatGPT, Cursor, and any MCP client\n- **Web Dashboard** — Beautiful dark-themed web UI with `homebutler serve`\n- **TUI Dashboard** — Real-time terminal monitoring with `homebutler watch` (btop-style)\n- **Wake-on-LAN** — Power on machines remotely\n- **Port Scanner** — See what's listening and which process owns it\n- **Network Scan** — Discover devices on your LAN\n- **JSON Output** — Pipe-friendly, perfect for AI assistants to parse\n\n\n### 📦 One-Command App Install\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/install-demo.gif\" alt=\"homebutler install demo\" width=\"900\"\u003e\n\u003c/p\u003e\n\n\u003e **`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)\n\n## Demo\n\n### 🌐 Web Dashboard\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/web-dashboard.png\" alt=\"homebutler web dashboard\" width=\"900\"\u003e\n\u003c/p\u003e\n\n\u003e **`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.\n\n\u003cdetails\u003e\n\u003csummary\u003e✨ Web Dashboard Highlights\u003c/summary\u003e\n\n- **Server Overview** — See all servers at a glance with color-coded status (green = online, red = offline)\n- **System Metrics** — CPU, memory, disk usage with progress bars and color thresholds\n- **Docker Containers** — Running/stopped status with friendly labels (\"Running · 4d\", \"Stopped · 6h ago\")\n- **Top Processes** — Top processes sorted by CPU/memory with zombie detection\n- **Resource Alerts** — Threshold-based warnings with visual progress bars (OK / WARNING / CRITICAL)\n- **Network Ports** — Open ports with process names and bind addresses\n- **Wake-on-LAN** — One-click wake buttons for configured devices\n- **Server Switching** — Dropdown to switch between local and remote servers\n- **Zero dependencies** — No Node.js runtime needed. Frontend is compiled into the Go binary at build time\n\n```bash\nhomebutler serve              # Start on port 8080\nhomebutler serve --port 3000  # Custom port\nhomebutler serve --demo       # Demo mode with realistic sample data\n```\n\n\u003c/details\u003e\n\n### 🖥️ TUI Dashboard\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"demo/demo-tui.gif\" alt=\"homebutler TUI dashboard\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003e **`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.\n\n### 🧠 AI-Powered Management (MCP)\n\n\u003e **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 \u0026 setup →](#mcp-server)\n\n## Quick Start\n\n```bash\n# One-line install (recommended, auto-detects OS/arch)\ncurl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh\n\n# Or via Homebrew\nbrew install Higangssh/homebutler/homebutler\n\n# Or via npm (MCP server only)\nnpm install -g homebutler\n\n# Interactive setup — adds your servers in seconds\nhomebutler init\n\n# Run\nhomebutler status\nhomebutler watch             # TUI dashboard (all servers)\nhomebutler serve             # Web dashboard at http://localhost:8080\nhomebutler docker list\nhomebutler wake desktop\nhomebutler ports\nhomebutler status --all\n\n# Install a self-hosted app (e.g. Uptime Kuma monitoring)\nhomebutler install uptime-kuma\n```\n\n## App Install\n\nDeploy self-hosted apps with a single command. Each app runs via **docker compose** with automatic pre-checks, health verification, and clean lifecycle management.\n\n```bash\n# List available apps\nhomebutler install list\n\n# Install (default port)\nhomebutler install uptime-kuma\n\n# Install with custom port\nhomebutler install uptime-kuma --port 8080\n\n# Install jellyfin with media directory\nhomebutler install jellyfin --media /mnt/movies\n\n# Check status\nhomebutler install status uptime-kuma\n\n# Stop (data preserved)\nhomebutler install uninstall uptime-kuma\n\n# Stop + delete everything\nhomebutler install purge uptime-kuma\n```\n\n### How it works\n\n```\n~/.homebutler/apps/\n  └── uptime-kuma/\n       ├── docker-compose.yml   ← auto-generated, editable\n       └── data/                ← persistent data (bind mount)\n```\n\n- **Pre-checks** — Verifies docker is installed/running, port is available, no duplicate containers\n- **Compose-based** — Each app gets its own `docker-compose.yml` you can inspect and customize\n- **Data safety** — `uninstall` stops containers but keeps your data; `purge` removes everything\n- **Cross-platform** — Auto-detects docker socket (default, colima, podman)\n\n### Available apps\n\n| App | Default Port | Description | Notes |\n|-----|-------------|-------------|-------|\n| `uptime-kuma` | 3001 | Self-hosted monitoring tool | |\n| `vaultwarden` | 8080 | Bitwarden-compatible password manager | |\n| `filebrowser` | 8081 | Web-based file manager | |\n| `it-tools` | 8082 | Developer utilities (JSON, Base64, Hash, etc.) | |\n| `gitea` | 3002 | Lightweight self-hosted Git service | |\n| `jellyfin` | 8096 | Media system (movies, TV, music) | `--media /path` to mount media dir |\n| `homepage` | 3010 | Modern homelab dashboard | |\n| `stirling-pdf` | 8083 | All-in-one PDF tool (merge, split, convert, OCR) | |\n| `speedtest-tracker` | 8084 | Internet speed test with historical graphs | |\n| `mealie` | 9925 | Recipe manager and meal planner | |\n| `pi-hole` | 8088 | DNS ad blocking | ⚠️ Uses port 53 (DNS), NET_ADMIN capability |\n| `adguard-home` | 3000 | DNS ad blocker and privacy | ⚠️ Uses port 53 (DNS) |\n| `portainer` | 9443 | Docker management GUI | ⚠️ Mounts Docker socket (HTTPS) |\n| `nginx-proxy-manager` | 81 | Reverse proxy with SSL and web UI | ⚠️ Uses ports 80/443 |\n\n### App-specific options\n\n```bash\n# Jellyfin: mount your media library\nhomebutler install jellyfin --media /mnt/movies\n\n# Pi-hole / AdGuard: DNS ad blocking (port 53 required)\nhomebutler install pi-hole\n# ⚠️ If port 53 is in use (Linux): sudo systemctl disable --now systemd-resolved\n\n# Portainer: Docker GUI (mounts docker socket)\nhomebutler install portainer\n# Access via HTTPS: https://localhost:9443\n\n# Nginx Proxy Manager: reverse proxy\nhomebutler install nginx-proxy-manager\n# Default login: admin@example.com / changeme (change immediately!)\n\n# Any app: custom port\nhomebutler install \u003capp\u003e --port 9999\n```\n\n### Safety checks\n\n- **Port conflict detection** — Checks if the port is already in use before install\n- **DNS mutual exclusion** — Warns if pi-hole and adguard-home are both installed\n- **Docker socket warning** — Alerts when an app requires Docker socket access (portainer)\n- **OS-specific guidance** — Linux gets systemd-resolved fix, macOS gets lsof command\n- **Post-install tips** — DNS setup, HTTPS access, default credential warnings\n\n\u003e Want more apps? [Open an issue](https://github.com/Higangssh/homebutler/issues) or see [Contributing](CONTRIBUTING.md).\n\n## Usage\n\n```\nhomebutler \u003ccommand\u003e [flags]\n\nCommands:\n  status              System status (CPU, memory, disk, uptime)\n  docker list         List running containers\n  install \u003capp\u003e       Install a self-hosted app (docker compose)\n  alerts              Show current alert status\n  watch               TUI dashboard (monitors all configured servers)\n  serve               Web dashboard (browser-based, go:embed)\n\nFlags:\n  --json              JSON output (default: human-readable)\n  --server \u003cname\u003e     Run on a specific remote server\n  --all               Run on all configured servers in parallel\n  --port \u003cnumber\u003e     Port for serve command (default: 8080)\n  --config \u003cpath\u003e     Config file (auto-detected, see Configuration)\n```\n\nRun `homebutler --help` for all commands.\n\n\u003cdetails\u003e\n\u003csummary\u003e📋 All Commands \u0026 Flags\u003c/summary\u003e\n\n```\nCommands:\n  init                Interactive setup wizard\n  status              System status (CPU, memory, disk, uptime)\n  watch               TUI dashboard (monitors all configured servers)\n  serve               Web dashboard (browser-based, go:embed)\n  docker list         List running containers\n  docker restart \u003cn\u003e  Restart a container\n  docker stop \u003cn\u003e     Stop a container\n  docker logs \u003cn\u003e     Show container logs\n  wake \u003cname\u003e         Send Wake-on-LAN packet\n  ports               List open ports with process info\n  ps                  Show top processes (alias: processes)\n  ps --sort mem       Sort by memory instead of CPU\n  ps --limit 20       Show top 20 (default: 10, 0 = all)\n  network scan        Discover devices on LAN\n  alerts              Show current alert status\n  alerts --watch      Continuous monitoring with real-time alerts\n  trust \u003cserver\u003e      Register SSH host key (TOFU)\n  backup              Backup Docker volumes, compose files, and env\n  backup list         List existing backups\n  backup drill \u003capp\u003e  Verify backup restores correctly (isolated)\n  backup drill --all  Verify all apps in backup\n  restore \u003carchive\u003e   Restore from a backup archive\n  upgrade             Upgrade local + all remote servers to latest\n  deploy              Install homebutler on remote servers\n  install \u003capp\u003e       Install a self-hosted app (docker compose)\n  install list        List available apps\n  install status \u003ca\u003e  Check installed app status\n  install uninstall   Stop app (keep data)\n  install purge       Stop app + delete all data\n  mcp                 Start MCP server (JSON-RPC over stdio)\n  version             Print version\n\nFlags:\n  --json              JSON output (default: human-readable)\n  --server \u003cname\u003e     Run on a specific remote server\n  --all               Run on all configured servers in parallel\n  --port \u003cnumber\u003e     Port for serve command (default: 8080)\n  --demo              Run serve with realistic demo data\n  --watch             Continuous monitoring mode (alerts command)\n  --interval \u003cdur\u003e    Watch interval, e.g. 30s, 1m (default: 30s)\n  --config \u003cpath\u003e     Config file (auto-detected, see Configuration)\n  --local             Upgrade only the local binary (skip remote servers)\n  --local \u003cpath\u003e      Use local binary for deploy (air-gapped)\n  --service \u003cname\u003e    Target a specific Docker service (backup/restore)\n  --to \u003cpath\u003e         Custom backup destination directory\n  --archive \u003cpath\u003e    Specific backup archive for drill\n  --all               Verify all supported apps (backup drill)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e🌐 Web Dashboard\u003c/summary\u003e\n\n`homebutler serve` starts an embedded web dashboard — no Node.js, no Docker, no extra dependencies.\n\n```bash\nhomebutler serve                # http://localhost:8080\nhomebutler serve --port 3000    # custom port\nhomebutler serve --demo         # demo mode with sample data\n```\n\n📖 **[Web dashboard details →](docs/web-dashboard.md)**\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e🖥️ TUI Dashboard\u003c/summary\u003e\n\n`homebutler watch` launches an interactive terminal dashboard (btop-style):\n\n```bash\nhomebutler watch               # monitors all configured servers\n```\n\nAuto-refreshes every 2 seconds. Press `q` to quit.\n\n\u003c/details\u003e\n\n## Alert Monitoring\n\n```bash\nhomebutler alerts --watch                  # default: 30s interval\nhomebutler alerts --watch --interval 10s   # check every 10 seconds\n```\n\nDefault thresholds: CPU 90%, Memory 85%, Disk 90%. Customizable via config.\n\n## Backup \u0026 Restore\n\nOne-command Docker backup — volumes, compose files, and env variables.\n\n```bash\nhomebutler backup                          # backup everything\nhomebutler backup --service jellyfin       # specific service\nhomebutler backup --to /mnt/nas/backups/   # custom destination\nhomebutler backup list                     # list backups\nhomebutler restore ./backup.tar.gz         # restore\n```\n\n\u003e ⚠️ Database services should be paused before backup for data consistency.\n\n📖 **[Full backup documentation →](docs/backup.md)** — how it works, archive structure, security notes.\n\n### 🛡️ Self-Healing\n\n**Your homelab fixes itself while you sleep.**\n\nDefine rules in YAML. homebutler watches your servers and takes action automatically — restart crashed containers, prune disk, or run custom scripts.\n\n```bash\nhomebutler alerts init          # interactive setup wizard\nhomebutler alerts --watch       # start self-healing daemon\nhomebutler alerts history       # view past events\nhomebutler alerts test-notify   # test your notification channels\n```\n\n**Example `~/.homebutler/alerts.yaml`:**\n\n```yaml\nrules:\n  - name: container-down\n    metric: container\n    watch: [uptime-kuma, vaultwarden]\n    action: restart\n    cooldown: 5m\n\n  - name: disk-full\n    metric: disk\n    threshold: 85\n    action: exec\n    exec: \"docker system prune -f\"\n\nnotify:\n  telegram:\n    bot_token: \"your-bot-token\"\n    chat_id: \"your-chat-id\"\n  slack:\n    webhook_url: \"https://hooks.slack.com/...\"\n  discord:\n    webhook_url: \"https://discord.com/api/webhooks/...\"\n```\n\n**What it does:**\n\n```\n⏱️ 03:14:22  🔴 disk-full triggered (disk 91%)\n             → Executing: docker system prune -f\n             → Reclaimed 4.2 GB\n✓  03:14:29  ✅ Resolved (disk 66%)\n```\n\n**Supported metrics:** `cpu`, `memory`, `disk`, `container`\n**Supported actions:** `notify` (alert only), `restart` (docker restart), `exec` (run any command)\n**Supported channels:** Telegram, Slack, Discord, generic webhook\n\n### 🔍 Backup Drill\n\n**\"Having a backup\" and \"being able to restore\" are different things.**\n\nBackup Drill boots your backup in an isolated Docker environment and verifies the app actually responds — like a fire drill for your data.\n\n```bash\nhomebutler backup drill uptime-kuma        # verify one app\nhomebutler backup drill --all              # verify all apps\nhomebutler backup drill --json             # machine-readable output\nhomebutler backup drill --archive ./file   # use a specific backup\n```\n\n**What happens:**\n1. Finds the latest backup archive\n2. Verifies archive integrity (`tar` validation)\n3. Creates an isolated Docker network + random port\n4. Boots the app from backup data\n5. Runs an HTTP health check\n6. Reports pass/fail and cleans up everything\n\n```\n🔍 Backup Drill — uptime-kuma\n\n  📦 Backup: ~/.homebutler/backups/backup_2026-04-04_1711.tar.gz\n  📏 Size: 18.6 MB\n  🔐 Integrity: ✅ tar valid (8 files)\n\n  🚀 Boot: ✅ container started in 0s\n  🌐 Health: ✅ HTTP 200 on port 58574\n  ⏱️  Total: 2s\n\n  ✅ DRILL PASSED\n```\n\n**Zero risk** — runs in a completely isolated environment. Your running services are never touched.\n\nSupports health checks for: `nginx-proxy-manager`, `vaultwarden`, `uptime-kuma`, `pi-hole`, `gitea`, `jellyfin`, `plex`, `portainer`, `homepage`, `adguard-home`.\n\n## Configuration\n\n```bash\nhomebutler init    # interactive setup wizard\n```\n\n📖 **[Configuration details →](docs/configuration.md)** — config file locations, alert thresholds, all options.\n\n## Multi-server\n\nManage multiple servers from a single machine over SSH.\n\n```bash\nhomebutler status --server rpi     # query specific server\nhomebutler status --all            # query all in parallel\nhomebutler deploy --server rpi     # install on remote server\nhomebutler upgrade                 # upgrade all servers\n```\n\n📖 **[Multi-server setup →](docs/multi-server.md)** — SSH auth, config examples, deploy \u0026 upgrade.\n\n## MCP Server\n\nBuilt-in [MCP](https://modelcontextprotocol.io/) server — manage your homelab from any AI tool with natural language.\n\n```json\n{\n  \"mcpServers\": {\n    \"homebutler\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"homebutler@latest\"]\n    }\n  }\n}\n```\n\nWorks with Claude Desktop, ChatGPT, Cursor, Windsurf, and any MCP client.\n\n📖 **[MCP server setup →](docs/mcp-server.md)** — supported clients, available tools, agent skills.\n\n## Installation\n\n### Homebrew (Recommended)\n\n```bash\nbrew install Higangssh/homebutler/homebutler\n```\n\nAutomatically installs to PATH. Works on macOS and Linux.\n\n### One-line Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh\n```\n\nAuto-detects OS/architecture, downloads the latest release, and installs to PATH.\n\n### npm (MCP server)\n\n```bash\nnpm install -g homebutler\n```\n\nDownloads the Go binary automatically. Use `npx -y homebutler@latest` to run without installing globally.\n\n### Go Install\n\n```bash\ngo install github.com/Higangssh/homebutler@latest\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/Higangssh/homebutler.git\ncd homebutler\nmake build\n```\n\n## Uninstall\n\n```bash\nrm $(which homebutler)           # Remove binary\nrm -rf ~/.config/homebutler      # Remove config (optional)\n```\n\n## Architecture\n\n\u003e **Goal: Engineers manage servers from chat — not SSH.**\n\u003e\n\u003e Alert fires → AI diagnoses → AI fixes → you get a summary on your phone.\n\nhomebutler 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.\n\n```\n┌──────────────────────────────────────────────────┐\n│  Layer 3 — Chat Interface                        │\n│  Telegram · Slack · Discord · Terminal · Browser │\n│  (Your choice — homebutler doesn't touch this)   │\n└──────────────────────┬───────────────────────────┘\n                       │\n┌──────────────────────▼───────────────────────────┐\n│  Layer 2 — AI Agent                              │\n│  OpenClaw · LangChain · n8n · Claude Desktop     │\n│  (Understands intent → calls the right tool)     │\n└──────────────────────┬───────────────────────────┘\n                       │  CLI exec or MCP (stdio)\n┌──────────────────────▼───────────────────────────┐\n│  Layer 1 — Tool (homebutler)       ← YOU ARE HERE │\n│                                                   │\n│  ┌─────────┐  ┌─────────┐  ┌─────────┐           │\n│  │   CLI   │  │   MCP   │  │   Web   │           │\n│  │ stdout  │  │  stdio  │  │  :8080  │           │\n│  └────┬────┘  └────┬────┘  └────┬────┘           │\n│       └────────────┼────────────┘                 │\n│                    ▼                              │\n│             internal/*                            │\n│   system · docker · ports · network               │\n│   wake · alerts · remote (SSH)                    │\n└───────────────────────────────────────────────────┘\n```\n\n**Three interfaces, one core:**\n\n| Interface | Transport | Use case |\n|-----------|-----------|----------|\n| **CLI** | Shell stdout/stderr | Terminal, scripts, AI agents via `exec` |\n| **MCP** | JSON-RPC over stdio | Claude Desktop, ChatGPT, Cursor, any MCP client |\n| **Web** | HTTP (`go:embed`) | Browser dashboard, on-demand with `homebutler serve` |\n\nAll three call the same `internal/` packages — no code duplication.\n\n**homebutler is Layer 1.** Swap Layer 2 and 3 to fit your stack:\n\n- **Terminal only** → `homebutler status` (no agent needed)\n- **Claude Desktop** → MCP server, Claude calls tools directly\n- **OpenClaw + Telegram** → Agent runs CLI commands from chat\n- **Custom Python bot** → `subprocess.run([\"homebutler\", \"status\", \"--json\"])`\n- **n8n / Dify** → Execute node calling homebutler CLI\n\n**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`).\n\n**Now:** CLI + MCP + Web dashboard — you ask, it answers.\n\n**Goal:** Full AI ChatOps — infrastructure that manages itself.\n\n\n\n## Contributing\n\nContributions welcome! Please open an issue first to discuss what you'd like to change.\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":["Cloud Infrastructure"],"sub_categories":["🐳 Container Orchestration"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHigangssh%2Fhomebutler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHigangssh%2Fhomebutler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHigangssh%2Fhomebutler/lists"}