Homeserver Management
Manage homelab servers using the homebutler CLI. Single binary, JSON output, AI-friendly.
Prerequisites
INLINECODE1 must be installed and available in PATH.
CODEBLOCK0
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/%)
Docker Management
CODEBLOCK3
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. Currently available: uptime-kuma, vaultwarden, filebrowser, it-tools, gitea.
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. Exposes all homebutler tools (system
status, dockerlist, docker
restart, dockerstop, docker
logs, wake, openports, network_scan, alerts) via standard MCP protocol. No network ports opened — uses stdio only.
Version
CODEBLOCK15
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 <path> — Explicit flag - INLINECODE12 — Environment variable
- INLINECODE13 — XDG standard (recommended)
- INLINECODE14 — Current directory
If no config found, sensible defaults are used.
Config Options
- -
servers — Server list with SSH connection details - INLINECODE16 — Named WOL targets with MAC + broadcast
- INLINECODE17 — Threshold percentages
- INLINECODE18 — Default output format
Multi-Server Config Example
CODEBLOCK16
Usage Guidelines
- 1. 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 INLINECODE20
- Use --server for specific — when user mentions a server by name, use INLINECODE21
- 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 INLINECODE25
- 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 <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
