homebutler

name homebutler description Homelab server operations via homebutler CLI/MCP. Check system status, generate butler reports, scan inventory/topology, manage Docker containers, install self-hosted apps, verify backup drills, Wake-on-LAN, port scanning, alerts, backup/restore, and multi-server SSH. metadata {"openclaw":{"emoji":"🏠","requires":{"anyBins":"[Truncated]"},"configPaths":["homebutler.yaml","~/.config/homebutler/config.yaml"]}} Homebutler Manage homelab servers using the homebutler CLI. Single binary, no daemon/database required, JSON output, MCP-friendly. Prerequisites homebutler must be installed and available in PATH. # Check if installed which homebutler # Option 1: Install via Homebrew (macOS/Linux) brew install Higangssh/homebutler/homebutler # Option 2: Install via Go go install github.com/Higangssh/homebutler@latest # Option 3: Build from source git clone https://github.com/Higangssh/homebutler.git cd homebutler && make build && sudo mv homebutler /usr/local/bin/ Commands Setup Wizard homebutler init # Interactive config setup Creates a config file at ~/.config/homebutler/config.yaml with guided prompts. System Status homebutler status # Local server homebutler status --server rpi # Specific remote server homebutler status --all # All servers in parallel Returns: hostname, OS, arch, uptime, CPU (usage%, cores), memory (total/used/%), disks (mount/total/used/%) Butler Report homebutler report # Health, warnings, changes, suggested actions homebutler report --no-save # Preview without writing a snapshot homebutler report --keep 7 # Retain latest 7 snapshots homebutler report --json # Structured output for automation/MCP Use this first when the user asks “how is my homelab/server doing?” and wants a concise operational summary. It snapshots current system/container/port state and compares it with the previous run. Inventory & Topology homebutler inventory scan # Tree view of system, containers, ports homebutler inventory scan --json # Structured inventory homebutler inventory export --format mermaid # Mermaid topology diagram Use this when the user asks what is running, which container owns a port, or wants topology/context for docs or AI analysis. Docker Management homebutler docker list # List all containers homebutler docker list --server rpi # List on remote server homebutler docker list --all # List on all servers homebutler docker restart <name> # Restart a container homebutler docker stop <name> # Stop a container homebutler docker logs <name> # Last 50 lines of logs homebutler docker logs <name> 200 # Last 200 lines Wake-on-LAN homebutler wake <mac-address> # Wake by MAC homebutler wake <name> # Wake by config name homebutler wake <mac> 192.168.1.255 # Custom broadcast Config names are defined in config under wake targets. Open Ports homebutler ports # Local homebutler ports --server rpi # Remote homebutler ports --all # All servers Returns: protocol, address, port, PID, process name Network Scan homebutler network scan Discovers devices on the local LAN via ping sweep + ARP table. Returns: IP, MAC, hostname, status. Note: May take up to 30 seconds. Some devices may not appear if they don't respond to ping. TUI Dashboard homebutler watch # Live terminal dashboard for all servers Real-time monitoring of all configured servers with auto-refresh. Shows CPU, memory, disk, docker containers in a terminal UI. Web Dashboard homebutler serve # Start web dashboard on port 8080 homebutler serve --port 3000 # Custom port homebutler serve --demo # Demo mode with fake data (no real system calls) Browser-based dashboard at http://localhost:8080 . Read-only view of all servers, docker containers, alerts. SSH Host Key Trust homebutler trust <server> # Trust remote server's SSH host key homebutler trust <server> --reset # Remove old key and re-trust TOFU (Trust On First Use) model. Required before first SSH connection to a new server. Upgrade homebutler upgrade # Upgrade local + all remote servers homebutler upgrade -- local # Upgrade only local binary Downloads latest release from GitHub and installs it. For remote servers, uses SSH to upgrade. Resource Alerts homebutler alerts # Local homebutler alerts --server rpi # Remote homebutler alerts --all # All servers Checks CPU/memory/disk against thresholds in config. Returns status (ok/warning/critical) per resource. Deploy (Remote Installation) homebutler deploy --server rpi # Download from GitHub Releases homebutler deploy --server rpi -- local ./homebutler # Air-gapped: copy local binary homebutler deploy --all # Deploy to all remote servers Installs homebutler on remote servers via SSH. Auto-detects remote OS/architecture. Install path priority: /usr/local/bin → sudo /usr/local/bin → ~/.local/bin (with PATH auto-registration in .profile/.bashrc/.zshrc). App Install homebutler install list # List available apps homebutler install <app> # Install an app (docker compose) homebutler install <app> --port 9090 # Custom port homebutler install status <app> # Check app status homebutler install uninstall <app> # Stop app, keep data homebutler install purge <app> # Stop + delete all data Deploys self-hosted apps via docker compose. Each app gets its own directory at ~/.homebutler/apps/<app>/ with auto-generated docker-compose.yml and persistent data. Pre-checks docker availability, port conflicts, and duplicates. Available apps include uptime-kuma, plex, vaultwarden, filebrowser, it-tools, gitea, jellyfin, homepage, stirling-pdf, speedtest-tracker, mealie, pi-hole, adguard-home, portainer, and nginx-proxy-manager. Backup, Restore & Backup Drill homebutler backup # Back up Docker compose volumes/files homebutler backup --service uptime-kuma # Back up one service homebutler backup list # List backup archives homebutler backup drill uptime-kuma # Boot backup in isolation and verify HTTP health homebutler backup drill --all # Drill every supported app in backup homebutler backup drill --archive ./file # Drill a specific archive homebutler restore ./backup.tar.gz # Restore volumes from archive Prefer backup drill when the user asks whether backups are trustworthy: it validates the archive, boots the app in an isolated Docker environment, health-checks it, and cleans up. MCP Server homebutler mcp # Start MCP server (JSON-RPC over stdio) Starts a built-in MCP (Model Context Protocol) server for use with Claude Desktop, ChatGPT, Cursor, and other MCP clients. No network ports opened — uses stdio only. Current MCP tools: system_status report inventory_scan , inventory_export docker_list , docker_restart , docker_stop , docker_logs , docker_stats , docker_top , docker_inspect wake , open_ports , network_scan , alerts backup_create , backup_list , backup_drill , backup_restore install_list , install_app , install_status , install_uninstall , install_purge proxmox_status , proxmox_guests , proxmox_node , proxmox_tasks , proxmox_guest_start , proxmox_guest_reboot , proxmox_guest_shutdown , proxmox_task_status , proxmox_script_list , proxmox_script_command Version homebutler version Output Format All commands output human-readable text by default. Use --json flag for machine-parseable JSON output (recommended for AI/script integration). Config File Config file is auto-discovered in order: --config <path> — Explicit flag $HOMEBUTLER_CONFIG — Environment variable ~/.config/homebutler/config.yaml — XDG standard (recommended) ./homebutler.yaml — Current directory If no config found, sensible defaults are used. Config Options servers — Server list with SSH connection details wake — Named WOL targets with MAC + broadcast alerts.cpu/memory/disk — Threshold percentages output — Default output format Multi-Server Config Example servers: - name: main-server host: 192.168 .1 .10 local: true - name: rpi host: 192.168 .1 .20 user: pi auth: key # "key" (default, recommended) or "password" key: ~/.ssh/id_ed25519 # optional, auto-detects - name: vps host: example.com user: deploy port: 2222 auth: key key: ~/.ssh/id_ed25519 Usage Guidelines Always run commands, don't guess — execute homebutler status to get real data Interpret results for the user — don't dump raw JSON, summarize in natural language Warn on alerts — if any resource shows "warning" or "critical", highlight it Use --all for overview — when user asks about "all servers" or "everything", use --all Use --server for specific — when user mentions a server by name, use --server <name> Docker errors — if docker is not installed or daemon not running, explain clearly Network scan — warn user it may take ~30 seconds Security — never expose raw JSON with hostnames/IPs in group chats, summarize instead Deploy — suggest --local for air-gapped environments Security Notes SSH authentication : Always prefer key-based auth over passwords. Never store plaintext passwords in config. Network scans : Only run on your own local network. Warn user before scanning. Deploy : Only deploy to servers you own. Confirm with user before remote installations. Config file permissions : Keep config files readable only by owner ( chmod 600 ). No telemetry : homebutler sends zero data externally. All operations are local or to user-configured hosts only. Error Handling SSH connection failed → Check host/port/user in config, verify SSH key is registered on remote homebutler not found on remote → Run homebutler deploy --server <name> first docker not installed → Tell user docker is not available on that server docker daemon not running → Suggest sudo systemctl start docker network scan timeout → Normal on large subnets, suggest retrying permission denied → May need sudo for ports/docker commands on some systems Example Interactions User: "How's the server doing?" → Prefer homebutler report , summarize health, warnings, notable changes, and suggested actions. Use homebutler status only for a raw point-in-time status. User: "What changed / what owns this port / map my homelab" → Run homebutler inventory scan or homebutler inventory export --format mermaid . User: "Check all servers" → Run homebutler status --all , summarize each server's status User: "How's the Raspberry Pi?" → Run homebutler status --server rpi , summarize User: "What docker containers are running?" → Run homebutler docker list , list container names and states User: "Wake up the NAS" → Run homebutler wake nas (if configured) or ask for MAC address User: "Any alerts across all servers?" → Run homebutler alerts --all , report any warnings/critical User: "Deploy homebutler to the new server" → Run homebutler deploy --server <name> , report result User: "Install uptime-kuma" → Run homebutler install uptime-kuma , report URL and status User: "What apps are available?" → Run homebutler install list , show available apps User: "Remove vaultwarden completely" → Run homebutler install purge vaultwarden , confirm deletion User: "Can I trust my backup?" → Run homebutler backup drill <app> or homebutler backup drill --all , report pass/fail and health status