Homeserver Management

Manage homelab servers using the homebutler CLI. Single binary, JSON output, AI-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

System Status

homebutler status                    # Local server
homebutler status --server rpi       # Specific remote server
homebutler status --all              # All servers in parallel

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

Open Ports

homebutler ports                     # Local
homebutler ports --server rpi        # Remote
homebutler ports --all               # All servers

Network Scan

homebutler network scan

TUI Dashboard

homebutler watch                     # Live terminal dashboard for all servers

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)

SSH Host Key Trust

homebutler trust <server>            # Trust remote server's SSH host key
homebutler trust <server> --reset    # Remove old key and re-trust

Upgrade

homebutler upgrade                   # Upgrade local + all remote servers
homebutler upgrade --local           # Upgrade only local binary

Resource Alerts

homebutler alerts                    # Local
homebutler alerts --server rpi       # Remote
homebutler alerts --all              # All servers

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

MCP Server

homebutler mcp                       # Start MCP server (JSON-RPC over stdio)

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 — Explicit flag
• $HOMEBUTLER_CONFIG — Environment variable
• ~/.config/homebutler/config.yaml — XDG standard (recommended)
• ./homebutler.yaml — Current directory

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
• 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 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?" → Run homebutler status, summarize: "CPU 23%, memory 40%, disk 37%. Uptime 42 days. All good 👍"

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