# Send Homeserver Management to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "homeserver", "name": "Homeserver Management", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/Higangssh/homeserver", "canonicalUrl": "https://clawhub.ai/Higangssh/homeserver", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/homeserver", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=homeserver", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "SKILL.md", "_meta.json" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "homeserver", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-04T04:13:55.291Z", "expiresAt": "2026-05-11T04:13:55.291Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=homeserver", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=homeserver", "contentDisposition": "attachment; filename=\"homeserver-2.3.2.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "homeserver" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/homeserver" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/homeserver", "downloadUrl": "https://openagent3.xyz/downloads/homeserver", "agentUrl": "https://openagent3.xyz/skills/homeserver/agent", "manifestUrl": "https://openagent3.xyz/skills/homeserver/agent.json", "briefUrl": "https://openagent3.xyz/skills/homeserver/agent.md" } } ``` ## Documentation ### 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/ ### 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 # Restart a container homebutler docker stop # Stop a container homebutler docker logs # Last 50 lines of logs homebutler docker logs 200 # Last 200 lines ### Wake-on-LAN homebutler wake # Wake by MAC homebutler wake # Wake by config name homebutler wake 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 # Trust remote server's SSH host key homebutler trust --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). ### 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 — 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 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 ## Trust - Source: tencent - Verification: Indexed source record - Publisher: Higangssh - Version: 2.1.0 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-05-04T04:13:55.291Z - Expires at: 2026-05-11T04:13:55.291Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/homeserver) - [Send to Agent page](https://openagent3.xyz/skills/homeserver/agent) - [JSON manifest](https://openagent3.xyz/skills/homeserver/agent.json) - [Markdown brief](https://openagent3.xyz/skills/homeserver/agent.md) - [Download page](https://openagent3.xyz/downloads/homeserver)