claw-works 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
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
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. 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, docker_list, docker_restart, docker_stop, docker_logs, wake, open_ports, network_scan, alerts) via standard MCP protocol. No network ports opened — uses stdio only.
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 detailswake— Named WOL targets with MAC + broadcastalerts.cpu/memory/disk— Threshold percentagesoutput— 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 statusto 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
--localfor 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?"
→ 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