Homeserver

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

Security Scan

The skill is an instruction-only wrapper around the homebutler CLI and its declared requirements and actions align with managing a homelab (SSH, Docker, wake-on-LAN, network scans, downloads from GitHub, local config files).

Purpose & Capability

Name/description match the instructions: the SKILL.md exclusively tells the agent to run the homebutler CLI to perform server status, Docker control, Wake-on-LAN, network scans, installs/upgrades, etc. The declared dependency (anyBins: ["homebutler"]) and config paths correspond to the stated purpose.

Instruction Scope

Instructions instruct the agent to run homebutler commands that perform network scans, SSH operations (deploy/upgrade/trust), download releases from GitHub, and read/write the homebutler config at ~/.config/homebutler/config.yaml. These behaviors are expected for a homelab management tool but are powerful: they can scan the local LAN, modify remote servers via SSH, and install or purge apps (including deleting app data).

Install Mechanism

There is no install spec in the skill bundle — it's instruction-only. The SKILL.md suggests installing homebutler via Homebrew, go install, or building from the project's GitHub; those are normal, traceable sources (GitHub, brew). No arbitrary download URL or archive extract is embedded in the skill itself.

Credentials

The skill requests no environment variables, which is proportional. However, many homebutler actions rely on the user's SSH keys, local ~/.ssh/known_hosts modifications (TOFU), Docker/socket access, and writing to ~/.config/homebutler; those implicit privileges are required by the tool but are not explicitly declared as credentials in the skill metadata.

Persistence & Privilege

always is false and the skill is user-invocable; it does not request permanent platform presence. The MCP server feature uses stdio per the doc (no network port opened by the skill itself). Agents invoking this skill will be able to run the underlying CLI, which is expected functionality.

Assessment

This skill is a wrapper for the homebutler CLI and appears internally consistent — but it gives the agent the ability to run powerful local and network operations through that binary. Before installing: (1) verify you trust the homebutler project/repo and prefer installing the binary from an official release or package manager rather than an unverified build; (2) be aware that homebutler will read/write ~/.config/homebutler and may modify ~/.ssh/known_hosts and use your SSH keys to control remote servers; (3) the tool can scan your LAN, stop/restart containers, install or purge apps (which can delete data), and download releases from GitHub — only grant it to agents you trust and consider running first in a non-critical environment; (4) if you are uncomfortable with automatic agent invocation, restrict usage to manual invocation or review CLI commands before execution.

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:

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

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