homeserver

# Homeserver Management Manage homelab servers using the [`homebutler`](https://github.com/Higangssh/homebutler) CLI. Single binary, JSON output, AI-friendly. ## Prerequisites `homebutler` must be installed and available in PATH. ```bash # 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 ```bash homebutler init # Interactive config setup ``` Creates a config file at `~/.config/homebutler/config.yaml` with guided prompts. ### System Status ```bash 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 ```bash 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 ```bash 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 ```bash homebutler ports # Local homebutler ports --server rpi # Remote homebutler ports --all # All servers ``` Returns: protocol, address, port, PID, process name ### Network Scan ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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) ```bash 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 ```bash 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 ```bash 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 ```bash 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 <path>` — 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 ```yaml 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 <name>` 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 <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