🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Homeserver
πŸ¦€ ClawHub

Homeserver

by @higangssh

Homelab server management via homebutler CLI. Check system status, manage Docker containers, install self-hosted apps, Wake-on-LAN, port scanning, alerts, ba...

Versionv2.2.1
Downloads385
Stars⭐ 1
#devops#legal#productivity
TERMINAL
clawhub install homeserver

πŸ“– About This Skill

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": ["homebutler"] }, "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      # Restart a container
homebutler docker stop         # Stop a container
homebutler docker logs         # Last 50 lines of logs
homebutler docker logs  200    # Last 200 lines

Wake-on-LAN

homebutler wake            # Wake by MAC
homebutler wake                    # Wake by config name
homebutler wake  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             # Trust remote server's SSH host key
homebutler trust  --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              # Install an app (docker compose)
homebutler install  --port 9090 # Custom port
homebutler install status       # Check app status
homebutler install uninstall    # Stop app, keep data
homebutler install purge        # Stop + delete all data
Deploys self-hosted apps via docker compose. Each app gets its own directory at ~/.homebutler/apps// 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
  • wake, open_ports, network_scan, alerts
  • backup_create, backup_list, backup_drill, backup_restore
  • install_list, install_app, install_status, install_uninstall, install_purge

    • 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: 1. --config β€” Explicit flag 2. $HOMEBUTLER_CONFIG β€” Environment variable 3. ~/.config/homebutler/config.yaml β€” XDG standard (recommended) 4. ./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

    1. Always run commands, don't guess β€” execute homebutler status to get real data 2. Interpret results for the user β€” don't dump raw JSON, summarize in natural language 3. Warn on alerts β€” if any resource shows "warning" or "critical", highlight it 4. Use --all for overview β€” when user asks about "all servers" or "everything", use --all 5. Use --server for specific β€” when user mentions a server by name, use --server 6. Docker errors β€” if docker is not installed or daemon not running, explain clearly 7. Network scan β€” warn user it may take ~30 seconds 8. Security β€” never expose raw JSON with hostnames/IPs in group chats, summarize instead 9. 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 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 , 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 or homebutler backup drill --all, report pass/fail and health status

    βš™οΈ Configuration

    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/