{"id":"fa98cb27-e792-4c1f-aa3e-5a990294f097","entityType":"agent","slug":"clawhub-higangssh-homebutler","name":"Skills","canonicalUrl":"https://www.xpersona.co/agent/clawhub-higangssh-homebutler","canonicalPath":"/agent/clawhub-higangssh-homebutler","generatedAt":"2026-10-10T21:51:05.968Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T16:44:59.176Z","emptyReason":null},"description":"Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive. Skill: Skills Owner: higangssh Summary: Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive. Tags: latest:2.4.0 Version history: v2.4.0 | 2026-09-26T01:25:35.512Z | user Pins moved to 0.39.0. v2.3.5 | 2026-09-16T14:46:41.508Z | user State when a read is appropriate, not only that it changes nothing; pin 0.35.2 v2.3","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.3K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17c6j8188dg65weva4qcvwhjn83t8y4:homebutler","sourceUrl":"https://clawhub.ai/higangssh/homebutler","homepage":"https://clawhub.ai/higangssh/skills/homebutler","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/higangssh/homebutler","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/higangssh/skills/homebutler","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive. Ski"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:44:59.176Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:44:59.176Z","emptyReason":null},"stars":null,"forks":null,"downloads":1333,"packageName":null,"latestVersion":"2.4.0","tractionLabel":"1.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:44:59.175Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T16:44:59.176Z","lastCrawledAt":"2026-10-10T16:44:59.175Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T16:44:59.175Z","lastVerifiedAt":null,"highlights":[{"version":"2.4.0","createdAt":"2026-09-26T01:25:35.512Z","changelog":"Pins moved to 0.39.0.","fileCount":3,"zipByteSize":6253},{"version":"2.3.5","createdAt":"2026-09-16T14:46:41.508Z","changelog":"State when a read is appropriate, not only that it changes nothing; pin 0.35.2","fileCount":3,"zipByteSize":5776},{"version":"2.3.4","createdAt":"2026-09-16T13:28:44.603Z","changelog":"Pin the installed version, verify release archives against checksums, and state the rule an agent follows for destructive tools","fileCount":3,"zipByteSize":5482},{"version":"2.3.3","createdAt":"2026-09-16T13:18:40.050Z","changelog":"Rewritten against 0.35.1: MCP tools first, doctor/Proxmox/ntfy/Gotify and the eight change kinds added, three stale descriptions corrected","fileCount":3,"zipByteSize":4758},{"version":"2.3.2","createdAt":"2026-05-03T04:05:10.637Z","changelog":"Display the skill name as Homebutler and keep the homebutler identity.","fileCount":3,"zipByteSize":6497},{"version":"0.18.1","createdAt":"2026-05-03T03:50:19.211Z","changelog":"Align the ClawHub skill with the Homebutler project name and current homebutler release line. Keep homeserver as a redirect to homebutler.","fileCount":2,"zipByteSize":5137},{"version":"2.3.1","createdAt":"2026-05-03T03:45:17.618Z","changelog":"Align skill branding with the new homebutler slug and keep homeserver as a redirect.","fileCount":2,"zipByteSize":5135},{"version":"2.3.0","createdAt":"2026-05-03T03:41:58.552Z","changelog":"Rename skill from homeserver to homebutler and refresh SKILL.md for recent homebutler features: report snapshots, inventory/topology export, backup drills, install tools, and expanded MCP operations.","fileCount":2,"zipByteSize":5141}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17c6j8188dg65weva4qcvwhjn83t8y4:homebutler","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-higangssh-homebutler/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-higangssh-homebutler/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-higangssh-homebutler/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-higangssh-homebutler/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-higangssh-homebutler/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-higangssh-homebutler/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T21:51:05.965Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-higangssh-homebutler/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-higangssh-homebutler/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-higangssh-homebutler/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-higangssh-homebutler/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T16:44:59.176Z","emptyReason":null},"readme":"Skill: Skills\n\nOwner: higangssh\n\nSummary: Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive.\n\nTags: latest:2.4.0\n\nVersion history:\n\nv2.4.0 | 2026-09-26T01:25:35.512Z | user\n\nPins moved to 0.39.0.\n\nv2.3.5 | 2026-09-16T14:46:41.508Z | user\n\nState when a read is appropriate, not only that it changes nothing; pin 0.35.2\n\nv2.3.4 | 2026-09-16T13:28:44.603Z | user\n\nPin the installed version, verify release archives against checksums, and state the rule an agent follows for destructive tools\n\nv2.3.3 | 2026-09-16T13:18:40.050Z | user\n\nRewritten against 0.35.1: MCP tools first, doctor/Proxmox/ntfy/Gotify and the eight change kinds added, three stale descriptions corrected\n\nv2.3.2 | 2026-05-03T04:05:10.637Z | user\n\nDisplay the skill name as Homebutler and keep the homebutler identity.\n\nv0.18.1 | 2026-05-03T03:50:19.211Z | user\n\nAlign the ClawHub skill with the Homebutler project name and current homebutler release line. Keep homeserver as a redirect to homebutler.\n\nv2.3.1 | 2026-05-03T03:45:17.618Z | user\n\nAlign skill branding with the new homebutler slug and keep homeserver as a redirect.\n\nv2.3.0 | 2026-05-03T03:41:58.552Z | user\n\nRename skill from homeserver to homebutler and refresh SKILL.md for recent homebutler features: report snapshots, inventory/topology export, backup drills, install tools, and expanded MCP operations.\n\nArchive index:\n\nArchive v2.4.0: 3 files, 6253 bytes\n\nFiles: skill-card.md (2019b), SKILL.md (11297b), _meta.json (129b)\n\nFile v2.4.0:SKILL.md\n\n---\nname: homebutler\ndescription: Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive.\nmetadata:\n {\n \"openclaw\": {\n \"emoji\": \"🏠\",\n \"requires\": { \"anyBins\": [\"homebutler\"] },\n \"configPaths\": [\"homebutler.yaml\", \"~/.config/homebutler/config.yaml\"]\n }\n }\n---\n\n# Homebutler\n\n[homebutler](https://github.com/Higangssh/homebutler) remembers what a server\nlooked like last time and reports only the changes worth mentioning. One Go\nbinary: no database, and no agent on the machines it watches — the binary is\ndeployed there once and runs only when asked, over SSH.\n\n> This file is published to ClawHub as `@higangssh/homebutler`. The copy that\n> matters lives in the repository at `skills/SKILL.md`, and a test in `cmd/`\n> fails the build when a command or a tool named here stops existing.\n\n## Use the MCP server, not the shell\n\nStart `homebutler mcp` and call tools. Every tool is classed **read**, **write**\nor **destructive**, and that classification is what lets an agent decide what it\nmay do unattended. Shell commands are for the handful of things no tool exposes,\nand for anything the operator has to run themselves.\n\n```bash\nhomebutler mcp\n```\n\n### The tools\n\n**Read (27)** — nothing changes; see what a read still exposes, below.\n\n- `system_status`, `processes`, `open_ports`, `alerts`, `alerts_history`\n- `doctor` — health, exposure, backup age and readiness, as findings\n- `inventory_scan`, `inventory_export`, `network_scan`, `config_validate`\n- `docker_list`, `docker_logs`, `docker_stats`, `docker_top`, `docker_inspect`\n- `backup_list`, `install_list`, `install_status`\n- `watch_list`, `watch_history`\n- `proxmox_status`, `proxmox_guests`, `proxmox_node`, `proxmox_tasks`,\n `proxmox_task_status`, `proxmox_script_list`, `proxmox_script_command`\n\n**Write (13)** — something changes, or something leaves the machine.\n\n- `report` — the comparison, and it saves a snapshot\n- `docker_restart`, `wake`, `notify_test`\n- `backup_create`, `backup_drill`\n- `install_app`, `install_uninstall`\n- `watch_add`, `watch_check`, `watch_remove`\n- `proxmox_guest_start`, `proxmox_guest_reboot`\n\n**Destructive (4)** — ask first.\n\n- `backup_restore` — overwrites volumes with an archive\n- `docker_stop`, `install_purge` — stops a service, deletes its data\n- `proxmox_guest_shutdown`\n\n### What the classes mean for you\n\n- **read** — changes nothing on the machine, so running one needs no\n confirmation. What comes back is another matter: hostnames, internal\n addresses, what is listening, what is running, log contents. So read the\n machine the operator is asking about rather than every machine in the config;\n `--all` and `inventory_scan` are answers to a question somebody asked, not a\n way to begin. Summarise what matters instead of returning raw logs, port\n tables or JSON into a conversation other people can read.\n- **write** — something changes on the machine, or a message leaves it. Do it when\n it follows from what was asked, and say afterwards what changed.\n- **destructive** — **never on your own initiative.** Only when the operator asked\n for that specific action on that specific target, in the turn you are answering.\n Do not infer one from a goal: \"free up space\" is not permission to run\n `install_purge`, and \"make it match production\" is not permission to run\n `backup_restore`.\n\n`backup_restore` and the Proxmox power tools take an explicit confirmation\nargument, so a call without it fails rather than proceeding. That is a backstop,\nnot the rule — the rule is that the operator asked.\n\nWhen an action is refused for lack of confirmation, say what would be destroyed\nand let the operator decide. Do not re-send the same call with the confirmation\nset.\n\nTwo things about reads that are easy to miss:\n\n- **A remote read is not free.** It is an SSH round trip to somebody's server,\n every time. Polling in a loop is a cost they pay.\n- **\"What changed?\" does not need a sweep.** `report` already answers it by\n comparing against the last snapshot, which is why it is the first thing to\n reach for rather than a tour of every tool.\n\n## Start here: what changed?\n\n`report` is the answer to \"how is my server doing?\" — it compares the machine\nagainst the last snapshot rather than describing the present.\n\nEach change carries a **kind**, and `--json` carries the same word, so branch on\nit rather than reading the sentence:\n\n| Kind | Means |\n| --- | --- |\n| `gone` | it was there last time and is not now |\n| `new` | it was not there last time and is now |\n| `replaced` | same name, different thing underneath — a recreated container |\n| `image` | same container, different image |\n| `state` | running where it was stopped, or the reverse |\n| `port` | same port, a different process answering on it |\n| `disk` | a mount moved by more than half a gigabyte |\n| `skipped` | the comparison could not be made — not an all-clear |\n\n```json\n{\"kind\": \"replaced\", \"target\": \"vaultwarden\",\n \"detail\": \"recreated, 4f2a1c → 9b7e03, vaultwarden:1.32 → vaultwarden:1.33\",\n \"text\": \"replaced: vaultwarden — recreated, …\"}\n```\n\n`needs_attention` and `suggested_actions` have the same shape. An action may\ncarry a `command`, and when it does it also carries `runner` and `tool`:\n\n- `runner: mcp` — call `tool` and carry it out\n- `runner: cli` — homebutler can do it, no tool exposes it; the operator runs it\n- `runner: shell` — not a homebutler command at all\n\nAn action with nothing to run — \"address the items above\" — has no `command`,\nand then no `runner` either. All three are omitted rather than sent empty, so\nabsence means there is nothing to offer rather than something unclassified.\n\n`doctor` findings carry the same three fields. **Check `runner` before offering\nto fix something.**\n\n## What needs a shell\n\n```bash\nhomebutler init\nhomebutler trust \nhomebutler watch install\nhomebutler watch tui\nhomebutler serve --token \nhomebutler serve install\nhomebutler deploy --server \nhomebutler upgrade\n```\n\nNo tool exposes any of these, and a test checks that against the registry\nrather than trusting this list.\n\n### `restore` has a tool, and you should still run it yourself\n\n`restore` writes over the data an app is running on, and the path it writes to\ncomes from the archive rather than from you — which is why the CLI refuses a\nbind mount unless you name the path with `--allow-bind`. There is a\n`backup_restore` tool, and over MCP it never restores bind mounts, for the same\nreason: an agent has no way to name a host path it is allowed to write to, so\nthe archive's bind mounts are refused and reported in the result.\n\n```bash\nhomebutler restore \n```\n\n### `trust`, and when it is required\n\n```bash\nhomebutler trust \nhomebutler trust --reset\n```\n\nSince **0.34.0**, a server that signs in with a **password** must be trusted\nbefore the first connection: homebutler will not send a password to a host it\nhas not been told to trust, because whatever answers at that address would\nreceive it. **Key authentication still trusts on first use** — the private key\nnever leaves the machine.\n\n### `watch` supervises, `watch tui` displays\n\n```bash\nhomebutler watch add \nhomebutler watch install\nhomebutler watch tui\n```\n\n`watch` is a restart tracker: it records incidents, captures the logs from the\nmoment a container went down, and notifies. `watch install` hands that loop to\nthe machine's own supervisor — a systemd user unit or a launchd agent — so it\nkeeps running after logout. That is the one part of homebutler that stays\nrunning, and it runs where the operator installed it, not on the machines it\nwatches. It is not a live dashboard — that is\n`watch tui`, and it is for a person rather than an agent.\n\n### `serve` edits, with a token\n\n```bash\nhomebutler serve\nhomebutler serve --token \nhomebutler serve --host 0.0.0.0 --token \nhomebutler serve install\n```\n\nSince **0.33.0** the dashboard edits the config file: alert thresholds,\nnotification channels, Wake-on-LAN devices, servers and Proxmox endpoints.\nWithout a token it is read-only and the write routes do not exist at all. The\ntoken can also live in the config file as `web.token`, which is where `serve\ninstall` reads it: a unit file is not homebutler's to protect, and `--token`\nis visible in `ps` to every user on the machine. The Report tab shows what\n`report` reports. There is a container image,\n`ghcr.io/higangssh/homebutler`, which reaches the machines in `servers:` over\nSSH — a container cannot see the host it runs on, and says so rather than\nanswering with its own numbers.\n\n## Notifications\n\nChannels: **telegram**, **slack**, **discord**, **webhook**, **ntfy**, **gotify**.\nntfy and Gotify are the two self-hosted push servers, and each takes its own\nshape rather than a webhook payload. Tokens travel in a header, never in a URL,\nso a failed request cannot put one in a log.\n\n```bash\nhomebutler notify test\n```\n\n`notify_test` reports each channel separately, so a failure names the channel\nthat failed rather than all of them.\n\n## Proxmox\n\nConfigured under `proxmox:` with an API token. The read credential and the one\nthat performs guest actions are separate: without an action token, start, reboot\nand shutdown are unavailable rather than falling back to the read credential.\n\n```bash\nhomebutler proxmox status\n```\n\n## Backups, and proving one comes back\n\n```bash\nhomebutler backup\nhomebutler backup list\nhomebutler backup drill \nhomebutler backup drill --all\nhomebutler restore \n```\n\n`backup drill` is the one to reach for when somebody asks whether backups are\ntrustworthy: it unpacks the archive into a container with a network and port of\nits own, starts the app on that data, and requires an HTTP health check to\nanswer.\n\n## Installing apps\n\n```bash\nhomebutler install list\nhomebutler install \nhomebutler install status \nhomebutler install uninstall \nhomebutler install purge \n```\n\n## Output and config\n\nEvery command takes `--json`. Commands that can reach another machine take\n`--server ` and `--all`.\n\nConfig is found in this order: `--config `, `$HOMEBUTLER_CONFIG`,\n`~/.config/homebutler/config.yaml`, `./homebutler.yaml`. Sections: `servers`,\n`wake`, `alerts`, `notify`, `proxmox`, `watch`, `backup`.\n\n```bash\nhomebutler config validate\n```\n\n## Prerequisites\n\nInstall a version, not whatever is newest at the moment the command runs. An\nagent that installs an unpinned executable cannot say what it ran.\n\n```bash\nbrew install Higangssh/homebutler/homebutler # pinned formula, our own tap\ngo install github.com/Higangssh/homebutler@v0.39.0\n```\n\nTaking a release archive instead means checking it against the checksums the\nrelease publishes:\n\n```bash\nV=0.39.0\nBASE=https://github.com/Higangssh/homebutler/releases/download/v$V\ncurl -fsSLO $BASE/homebutler_${V}_linux_amd64.tar.gz\ncurl -fsSLO $BASE/checksums.txt\nsha256sum --check --ignore-missing checksums.txt # macOS: shasum -a 256 --check …\n# must print: homebutler_0.39.0_linux_amd64.tar.gz: OK\ntar xzf homebutler_${V}_linux_amd64.tar.gz\n```\n\nThere is a container image, `ghcr.io/higangssh/homebutler:0.39.0`, pinned the\nsame way.\n\nFile v2.4.0:_meta.json\n\n{\n \"ownerId\": \"kn79fa6trrr94j7388baz1wan581qrrg\",\n \"slug\": \"homebutler\",\n \"version\": \"2.4.0\",\n \"publishedAt\": 1790385935512\n}\n\nFile v2.4.0:skill-card.md\n\n## Description:\n\nHelps agents identify server changes and check system health, Docker, backups, and Proxmox through Homebutler.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[higangssh](https://clawhub.ai/user/higangssh)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nServer administrators and developers use this skill to review changes and health across configured servers, inspect Docker and backups, and request scoped maintenance or Proxmox actions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Server scans and diagnostic results may expose hostnames, internal addresses, ports, or log contents.\n\nMitigation: Limit reads to the requested hosts, seek approval for broad scans, and summarize sensitive results instead of sharing raw output.\n\nRisk: Write, restore, purge, service, and Proxmox power actions can change or delete operational data.\n\nMitigation: Require explicit operator approval for the specific target and action before execution; review configuration and backups first.\n\nRisk: Configured SSH access and tokens can grant control over monitored servers and Proxmox guests.\n\nMitigation: Review Homebutler configuration, tokens, and SSH access before installation and use.\n\n## Reference(s):\n\n- [Homebutler on ClawHub](https://clawhub.ai/higangssh/skills/homebutler)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Guidance, Shell commands, Configuration instructions]\n\n**Output Format:** [Markdown with optional structured tool results]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Summarized changes, findings, and suggested actions; command results can be requested as JSON.]\n\n## Skill Version(s):\n\n2.4.0 (source: ClawHub release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.3.5: 3 files, 5776 bytes\n\nFiles: skill-card.md (2186b), SKILL.md (9891b), _meta.json (129b)\n\nFile v2.3.5:SKILL.md\n\n---\nname: homebutler\ndescription: Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive.\nmetadata:\n {\n \"openclaw\": {\n \"emoji\": \"🏠\",\n \"requires\": { \"anyBins\": [\"homebutler\"] },\n \"configPaths\": [\"homebutler.yaml\", \"~/.config/homebutler/config.yaml\"]\n }\n }\n---\n\n# Homebutler\n\n[homebutler](https://github.com/Higangssh/homebutler) remembers what a server\nlooked like last time and reports only the changes worth mentioning. One Go\nbinary: no daemon, no database, no agent on the machines it watches — the\nbinary is deployed there once and runs only when asked, over SSH.\n\n> This file is published to ClawHub as `@higangssh/homebutler`. The copy that\n> matters lives in the repository at `skills/SKILL.md`, and a test in `cmd/`\n> fails the build when a command or a tool named here stops existing.\n\n## Use the MCP server, not the shell\n\nStart `homebutler mcp` and call tools. Every tool is classed **read**, **write**\nor **destructive**, and that classification is what lets an agent decide what it\nmay do unattended. Shell commands are for the handful of things no tool exposes,\nand for anything the operator has to run themselves.\n\n```bash\nhomebutler mcp\n```\n\n### The tools\n\n**Read (27)** — nothing changes; see what a read still exposes, below.\n\n- `system_status`, `processes`, `open_ports`, `alerts`, `alerts_history`\n- `doctor` — health, exposure, backup age and readiness, as findings\n- `inventory_scan`, `inventory_export`, `network_scan`, `config_validate`\n- `docker_list`, `docker_logs`, `docker_stats`, `docker_top`, `docker_inspect`\n- `backup_list`, `install_list`, `install_status`\n- `watch_list`, `watch_history`\n- `proxmox_status`, `proxmox_guests`, `proxmox_node`, `proxmox_tasks`,\n `proxmox_task_status`, `proxmox_script_list`, `proxmox_script_command`\n\n**Write (13)** — something changes, or something leaves the machine.\n\n- `report` — the comparison, and it saves a snapshot\n- `docker_restart`, `wake`, `notify_test`\n- `backup_create`, `backup_drill`\n- `install_app`, `install_uninstall`\n- `watch_add`, `watch_check`, `watch_remove`\n- `proxmox_guest_start`, `proxmox_guest_reboot`\n\n**Destructive (4)** — ask first.\n\n- `backup_restore` — overwrites volumes with an archive\n- `docker_stop`, `install_purge` — stops a service, deletes its data\n- `proxmox_guest_shutdown`\n\n### What the classes mean for you\n\n- **read** — changes nothing on the machine, so running one needs no\n confirmation. What comes back is another matter: hostnames, internal\n addresses, what is listening, what is running, log contents. So read the\n machine the operator is asking about rather than every machine in the config;\n `--all` and `inventory_scan` are answers to a question somebody asked, not a\n way to begin. Summarise what matters instead of returning raw logs, port\n tables or JSON into a conversation other people can read.\n- **write** — something changes on the machine, or a message leaves it. Do it when\n it follows from what was asked, and say afterwards what changed.\n- **destructive** — **never on your own initiative.** Only when the operator asked\n for that specific action on that specific target, in the turn you are answering.\n Do not infer one from a goal: \"free up space\" is not permission to run\n `install_purge`, and \"make it match production\" is not permission to run\n `backup_restore`.\n\n`backup_restore` and the Proxmox power tools take an explicit confirmation\nargument, so a call without it fails rather than proceeding. That is a backstop,\nnot the rule — the rule is that the operator asked.\n\nWhen an action is refused for lack of confirmation, say what would be destroyed\nand let the operator decide. Do not re-send the same call with the confirmation\nset.\n\nTwo things about reads that are easy to miss:\n\n- **A remote read is not free.** It is an SSH round trip to somebody's server,\n every time. Polling in a loop is a cost they pay.\n- **\"What changed?\" does not need a sweep.** `report` already answers it by\n comparing against the last snapshot, which is why it is the first thing to\n reach for rather than a tour of every tool.\n\n## Start here: what changed?\n\n`report` is the answer to \"how is my server doing?\" — it compares the machine\nagainst the last snapshot rather than describing the present.\n\nEach change carries a **kind**, and `--json` carries the same word, so branch on\nit rather than reading the sentence:\n\n| Kind | Means |\n| --- | --- |\n| `gone` | it was there last time and is not now |\n| `new` | it was not there last time and is now |\n| `replaced` | same name, different thing underneath — a recreated container |\n| `image` | same container, different image |\n| `state` | running where it was stopped, or the reverse |\n| `port` | same port, a different process answering on it |\n| `disk` | a mount moved by more than half a gigabyte |\n| `skipped` | the comparison could not be made — not an all-clear |\n\n```json\n{\"kind\": \"replaced\", \"target\": \"vaultwarden\",\n \"detail\": \"recreated, 4f2a1c → 9b7e03, vaultwarden:1.32 → vaultwarden:1.33\",\n \"text\": \"replaced: vaultwarden — recreated, …\"}\n```\n\n`needs_attention` and `suggested_actions` have the same shape. An action carries\n`command`, plus `runner` and `tool`:\n\n- `runner: mcp` — call `tool` and carry it out\n- `runner: cli` — homebutler can do it, no tool exposes it; the operator runs it\n- `runner: shell` — not a homebutler command at all\n\n`doctor` findings carry the same three fields. **Check `runner` before offering\nto fix something.**\n\n## What needs a shell\n\n```bash\nhomebutler init\nhomebutler trust \nhomebutler watch install\nhomebutler watch tui\nhomebutler serve --token \nhomebutler deploy --server \nhomebutler upgrade\nhomebutler notify test\nhomebutler restore \n```\n\n### `trust`, and when it is required\n\n```bash\nhomebutler trust \nhomebutler trust --reset\n```\n\nSince **0.34.0**, a server that signs in with a **password** must be trusted\nbefore the first connection: homebutler will not send a password to a host it\nhas not been told to trust, because whatever answers at that address would\nreceive it. **Key authentication still trusts on first use** — the private key\nnever leaves the machine.\n\n### `watch` supervises, `watch tui` displays\n\n```bash\nhomebutler watch add \nhomebutler watch install\nhomebutler watch tui\n```\n\n`watch` is a restart tracker: it records incidents, captures the logs from the\nmoment a container went down, and notifies. It is not a live dashboard — that is\n`watch tui`, and it is for a person rather than an agent.\n\n### `serve` edits, with a token\n\n```bash\nhomebutler serve\nhomebutler serve --token \nhomebutler serve --host 0.0.0.0 --token \n```\n\nSince **0.33.0** the dashboard edits the config file: alert thresholds,\nnotification channels, Wake-on-LAN devices, servers and Proxmox endpoints.\nWithout `--token` it is read-only and the write routes do not exist at all. The\nReport tab shows what `report` reports. There is a container image,\n`ghcr.io/higangssh/homebutler`, which reaches the machines in `servers:` over\nSSH — a container cannot see the host it runs on, and says so rather than\nanswering with its own numbers.\n\n## Notifications\n\nChannels: **telegram**, **slack**, **discord**, **webhook**, **ntfy**, **gotify**.\nntfy and Gotify are the two self-hosted push servers, and each takes its own\nshape rather than a webhook payload. Tokens travel in a header, never in a URL,\nso a failed request cannot put one in a log.\n\n```bash\nhomebutler notify test\n```\n\n`notify_test` reports each channel separately, so a failure names the channel\nthat failed rather than all of them.\n\n## Proxmox\n\nConfigured under `proxmox:` with an API token. The read credential and the one\nthat performs guest actions are separate: without an action token, start, reboot\nand shutdown are unavailable rather than falling back to the read credential.\n\n```bash\nhomebutler proxmox status\n```\n\n## Backups, and proving one comes back\n\n```bash\nhomebutler backup\nhomebutler backup list\nhomebutler backup drill \nhomebutler backup drill --all\nhomebutler restore \n```\n\n`backup drill` is the one to reach for when somebody asks whether backups are\ntrustworthy: it unpacks the archive into a container with a network and port of\nits own, starts the app on that data, and requires an HTTP health check to\nanswer.\n\n## Installing apps\n\n```bash\nhomebutler install list\nhomebutler install \nhomebutler install status \nhomebutler install uninstall \nhomebutler install purge \n```\n\n## Output and config\n\nEvery command takes `--json`. Commands that can reach another machine take\n`--server ` and `--all`.\n\nConfig is found in this order: `--config `, `$HOMEBUTLER_CONFIG`,\n`~/.config/homebutler/config.yaml`, `./homebutler.yaml`. Sections: `servers`,\n`wake`, `alerts`, `notify`, `proxmox`, `watch`, `backup`.\n\n```bash\nhomebutler config validate\n```\n\n## Prerequisites\n\nInstall a version, not whatever is newest at the moment the command runs. An\nagent that installs an unpinned executable cannot say what it ran.\n\n```bash\nbrew install Higangssh/homebutler/homebutler # pinned formula, our own tap\ngo install github.com/Higangssh/homebutler@v0.35.2\n```\n\nTaking a release archive instead means checking it against the checksums the\nrelease publishes:\n\n```bash\nV=0.35.2\nBASE=https://github.com/Higangssh/homebutler/releases/download/v$V\ncurl -fsSLO $BASE/homebutler_${V}_linux_amd64.tar.gz\ncurl -fsSLO $BASE/checksums.txt\nsha256sum --check --ignore-missing checksums.txt # macOS: shasum -a 256 --check …\n# must print: homebutler_0.35.2_linux_amd64.tar.gz: OK\ntar xzf homebutler_${V}_linux_amd64.tar.gz\n```\n\nThere is a container image, `ghcr.io/higangssh/homebutler:0.35.2`, pinned the\nsame way.\n\nFile v2.3.5:_meta.json\n\n{\n \"ownerId\": \"kn79fa6trrr94j7388baz1wan581qrrg\",\n \"slug\": \"homebutler\",\n \"version\": \"2.3.5\",\n \"publishedAt\": 1789570001508\n}\n\nFile v2.3.5:skill-card.md\n\n## Description:\n\nTells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[higangssh](https://clawhub.ai/user/higangssh)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, operators, and self-hosting administrators use this skill to let an agent inspect configured servers, summarize meaningful changes, and manage Docker, backups, Proxmox guests, alerts, and install workflows through classified MCP tools.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can inspect configured servers and return operational details such as hostnames, internal addresses, ports, processes, and logs.\n\nMitigation: Run reads only against requested targets and summarize relevant findings instead of exposing raw logs or broad inventory data.\n\nRisk: The skill can perform write or destructive operations including restore, purge, stop, shutdown, restart, install, and Proxmox guest actions.\n\nMitigation: Require explicit operator approval for destructive actions and review configured tokens, SSH credentials, and dashboard exposure before use.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/higangssh/skills/homebutler)\n- [Publisher profile](https://clawhub.ai/user/higangssh)\n- [Homebutler repository](https://github.com/Higangssh/homebutler)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline JSON and shell command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include MCP tool calls or pinned install and configuration commands; destructive actions require explicit operator approval.]\n\n## Skill Version(s):\n\n2.3.5 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.3.4: 3 files, 5482 bytes\n\nFiles: skill-card.md (2300b), SKILL.md (9055b), _meta.json (129b)\n\nFile v2.3.4:SKILL.md\n\n---\nname: homebutler\ndescription: Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive.\nmetadata:\n {\n \"openclaw\": {\n \"emoji\": \"🏠\",\n \"requires\": { \"anyBins\": [\"homebutler\"] },\n \"configPaths\": [\"homebutler.yaml\", \"~/.config/homebutler/config.yaml\"]\n }\n }\n---\n\n# Homebutler\n\n[homebutler](https://github.com/Higangssh/homebutler) remembers what a server\nlooked like last time and reports only the changes worth mentioning. One Go\nbinary: no daemon, no database, no agent on the machines it watches — the\nbinary is deployed there once and runs only when asked, over SSH.\n\n> This file is published to ClawHub as `@higangssh/homebutler`. The copy that\n> matters lives in the repository at `skills/SKILL.md`, and a test in `cmd/`\n> fails the build when a command or a tool named here stops existing.\n\n## Use the MCP server, not the shell\n\nStart `homebutler mcp` and call tools. Every tool is classed **read**, **write**\nor **destructive**, and that classification is what lets an agent decide what it\nmay do unattended. Shell commands are for the handful of things no tool exposes,\nand for anything the operator has to run themselves.\n\n```bash\nhomebutler mcp\n```\n\n### The tools\n\n**Read (27)** — safe to call unattended.\n\n- `system_status`, `processes`, `open_ports`, `alerts`, `alerts_history`\n- `doctor` — health, exposure, backup age and readiness, as findings\n- `inventory_scan`, `inventory_export`, `network_scan`, `config_validate`\n- `docker_list`, `docker_logs`, `docker_stats`, `docker_top`, `docker_inspect`\n- `backup_list`, `install_list`, `install_status`\n- `watch_list`, `watch_history`\n- `proxmox_status`, `proxmox_guests`, `proxmox_node`, `proxmox_tasks`,\n `proxmox_task_status`, `proxmox_script_list`, `proxmox_script_command`\n\n**Write (13)** — something changes, or something leaves the machine.\n\n- `report` — the comparison, and it saves a snapshot\n- `docker_restart`, `wake`, `notify_test`\n- `backup_create`, `backup_drill`\n- `install_app`, `install_uninstall`\n- `watch_add`, `watch_check`, `watch_remove`\n- `proxmox_guest_start`, `proxmox_guest_reboot`\n\n**Destructive (4)** — ask first.\n\n- `backup_restore` — overwrites volumes with an archive\n- `docker_stop`, `install_purge` — stops a service, deletes its data\n- `proxmox_guest_shutdown`\n\n### What the classes mean for you\n\n- **read** — call it unattended. Nothing changes and nothing leaves the machine.\n- **write** — something changes on the machine, or a message leaves it. Do it when\n it follows from what was asked, and say afterwards what changed.\n- **destructive** — **never on your own initiative.** Only when the operator asked\n for that specific action on that specific target, in the turn you are answering.\n Do not infer one from a goal: \"free up space\" is not permission to run\n `install_purge`, and \"make it match production\" is not permission to run\n `backup_restore`.\n\n`backup_restore` and the Proxmox power tools take an explicit confirmation\nargument, so a call without it fails rather than proceeding. That is a backstop,\nnot the rule — the rule is that the operator asked.\n\nWhen an action is refused for lack of confirmation, say what would be destroyed\nand let the operator decide. Do not re-send the same call with the confirmation\nset.\n\n## Start here: what changed?\n\n`report` is the answer to \"how is my server doing?\" — it compares the machine\nagainst the last snapshot rather than describing the present.\n\nEach change carries a **kind**, and `--json` carries the same word, so branch on\nit rather than reading the sentence:\n\n| Kind | Means |\n| --- | --- |\n| `gone` | it was there last time and is not now |\n| `new` | it was not there last time and is now |\n| `replaced` | same name, different thing underneath — a recreated container |\n| `image` | same container, different image |\n| `state` | running where it was stopped, or the reverse |\n| `port` | same port, a different process answering on it |\n| `disk` | a mount moved by more than half a gigabyte |\n| `skipped` | the comparison could not be made — not an all-clear |\n\n```json\n{\"kind\": \"replaced\", \"target\": \"vaultwarden\",\n \"detail\": \"recreated, 4f2a1c → 9b7e03, vaultwarden:1.32 → vaultwarden:1.33\",\n \"text\": \"replaced: vaultwarden — recreated, …\"}\n```\n\n`needs_attention` and `suggested_actions` have the same shape. An action carries\n`command`, plus `runner` and `tool`:\n\n- `runner: mcp` — call `tool` and carry it out\n- `runner: cli` — homebutler can do it, no tool exposes it; the operator runs it\n- `runner: shell` — not a homebutler command at all\n\n`doctor` findings carry the same three fields. **Check `runner` before offering\nto fix something.**\n\n## What needs a shell\n\n```bash\nhomebutler init\nhomebutler trust \nhomebutler watch install\nhomebutler watch tui\nhomebutler serve --token \nhomebutler deploy --server \nhomebutler upgrade\nhomebutler notify test\nhomebutler restore \n```\n\n### `trust`, and when it is required\n\n```bash\nhomebutler trust \nhomebutler trust --reset\n```\n\nSince **0.34.0**, a server that signs in with a **password** must be trusted\nbefore the first connection: homebutler will not send a password to a host it\nhas not been told to trust, because whatever answers at that address would\nreceive it. **Key authentication still trusts on first use** — the private key\nnever leaves the machine.\n\n### `watch` supervises, `watch tui` displays\n\n```bash\nhomebutler watch add \nhomebutler watch install\nhomebutler watch tui\n```\n\n`watch` is a restart tracker: it records incidents, captures the logs from the\nmoment a container went down, and notifies. It is not a live dashboard — that is\n`watch tui`, and it is for a person rather than an agent.\n\n### `serve` edits, with a token\n\n```bash\nhomebutler serve\nhomebutler serve --token \nhomebutler serve --host 0.0.0.0 --token \n```\n\nSince **0.33.0** the dashboard edits the config file: alert thresholds,\nnotification channels, Wake-on-LAN devices, servers and Proxmox endpoints.\nWithout `--token` it is read-only and the write routes do not exist at all. The\nReport tab shows what `report` reports. There is a container image,\n`ghcr.io/higangssh/homebutler`, which reaches the machines in `servers:` over\nSSH — a container cannot see the host it runs on, and says so rather than\nanswering with its own numbers.\n\n## Notifications\n\nChannels: **telegram**, **slack**, **discord**, **webhook**, **ntfy**, **gotify**.\nntfy and Gotify are the two self-hosted push servers, and each takes its own\nshape rather than a webhook payload. Tokens travel in a header, never in a URL,\nso a failed request cannot put one in a log.\n\n```bash\nhomebutler notify test\n```\n\n`notify_test` reports each channel separately, so a failure names the channel\nthat failed rather than all of them.\n\n## Proxmox\n\nConfigured under `proxmox:` with an API token. The read credential and the one\nthat performs guest actions are separate: without an action token, start, reboot\nand shutdown are unavailable rather than falling back to the read credential.\n\n```bash\nhomebutler proxmox status\n```\n\n## Backups, and proving one comes back\n\n```bash\nhomebutler backup\nhomebutler backup list\nhomebutler backup drill \nhomebutler backup drill --all\nhomebutler restore \n```\n\n`backup drill` is the one to reach for when somebody asks whether backups are\ntrustworthy: it unpacks the archive into a container with a network and port of\nits own, starts the app on that data, and requires an HTTP health check to\nanswer.\n\n## Installing apps\n\n```bash\nhomebutler install list\nhomebutler install \nhomebutler install status \nhomebutler install uninstall \nhomebutler install purge \n```\n\n## Output and config\n\nEvery command takes `--json`. Commands that can reach another machine take\n`--server ` and `--all`.\n\nConfig is found in this order: `--config `, `$HOMEBUTLER_CONFIG`,\n`~/.config/homebutler/config.yaml`, `./homebutler.yaml`. Sections: `servers`,\n`wake`, `alerts`, `notify`, `proxmox`, `watch`, `backup`.\n\n```bash\nhomebutler config validate\n```\n\n## Prerequisites\n\nInstall a version, not whatever is newest at the moment the command runs. An\nagent that installs an unpinned executable cannot say what it ran.\n\n```bash\nbrew install Higangssh/homebutler/homebutler # pinned formula, our own tap\ngo install github.com/Higangssh/homebutler@v0.35.1\n```\n\nTaking a release archive instead means checking it against the checksums the\nrelease publishes:\n\n```bash\nV=0.35.1\nBASE=https://github.com/Higangssh/homebutler/releases/download/v$V\ncurl -fsSLO $BASE/homebutler_${V}_linux_amd64.tar.gz\ncurl -fsSLO $BASE/checksums.txt\nsha256sum --check --ignore-missing checksums.txt # macOS: shasum -a 256 --check …\n# must print: homebutler_0.35.1_linux_amd64.tar.gz: OK\ntar xzf homebutler_${V}_linux_amd64.tar.gz\n```\n\nThere is a container image, `ghcr.io/higangssh/homebutler:0.35.1`, pinned the\nsame way.\n\nFile v2.3.4:_meta.json\n\n{\n \"ownerId\": \"kn79fa6trrr94j7388baz1wan581qrrg\",\n \"slug\": \"homebutler\",\n \"version\": \"2.3.4\",\n \"publishedAt\": 1789565324603\n}\n\nFile v2.3.4:skill-card.md\n\n## Description:\n\nTells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[higangssh](https://clawhub.ai/user/higangssh)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal operators and infrastructure engineers use homebutler to let an agent inspect server changes, Docker state, backups, Proxmox status, and related operational findings through classified MCP tools.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can expose sensitive operational details from configured servers, containers, logs, network scans, backups, and Proxmox.\n\nMitigation: Limit Homebutler credentials and configured targets, avoid broad --all use unless intended, and require explicit user approval for sensitive reads such as docker_logs, docker_inspect, network_scan, and inventory_export.\n\nRisk: The skill includes write and destructive operations that can change infrastructure state or overwrite data.\n\nMitigation: Require explicit user approval for destructive operations and confirm the specific target before backup_restore, docker_stop, install_purge, or Proxmox shutdown actions.\n\nRisk: Exposing the dashboard on 0.0.0.0 can increase administrative attack surface.\n\nMitigation: Do not expose serve on 0.0.0.0 without strong surrounding controls, and use token-protected write access when dashboard edits are enabled.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/higangssh/skills/homebutler)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline command examples and tool names]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include MCP tool recommendations and operational cautions based on server-management context.]\n\n## Skill Version(s):\n\n2.3.4 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.3.3: 3 files, 4758 bytes\n\nFiles: skill-card.md (2239b), SKILL.md (7345b), _meta.json (129b)\n\nFile v2.3.3:SKILL.md\n\n---\nname: homebutler\ndescription: Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive.\nmetadata:\n {\n \"openclaw\": {\n \"emoji\": \"🏠\",\n \"requires\": { \"anyBins\": [\"homebutler\"] },\n \"configPaths\": [\"homebutler.yaml\", \"~/.config/homebutler/config.yaml\"]\n }\n }\n---\n\n# Homebutler\n\n[homebutler](https://github.com/Higangssh/homebutler) remembers what a server\nlooked like last time and reports only the changes worth mentioning. One Go\nbinary: no daemon, no database, no agent on the machines it watches — the\nbinary is deployed there once and runs only when asked, over SSH.\n\n> This file is published to ClawHub as `@higangssh/homebutler`. The copy that\n> matters lives in the repository at `skills/SKILL.md`, and a test in `cmd/`\n> fails the build when a command or a tool named here stops existing.\n\n## Use the MCP server, not the shell\n\nStart `homebutler mcp` and call tools. Every tool is classed **read**, **write**\nor **destructive**, and that classification is what lets an agent decide what it\nmay do unattended. Shell commands are for the handful of things no tool exposes,\nand for anything the operator has to run themselves.\n\n```bash\nhomebutler mcp\n```\n\n### The tools\n\n**Read (27)** — safe to call unattended.\n\n- `system_status`, `processes`, `open_ports`, `alerts`, `alerts_history`\n- `doctor` — health, exposure, backup age and readiness, as findings\n- `inventory_scan`, `inventory_export`, `network_scan`, `config_validate`\n- `docker_list`, `docker_logs`, `docker_stats`, `docker_top`, `docker_inspect`\n- `backup_list`, `install_list`, `install_status`\n- `watch_list`, `watch_history`\n- `proxmox_status`, `proxmox_guests`, `proxmox_node`, `proxmox_tasks`,\n `proxmox_task_status`, `proxmox_script_list`, `proxmox_script_command`\n\n**Write (13)** — something changes, or something leaves the machine.\n\n- `report` — the comparison, and it saves a snapshot\n- `docker_restart`, `wake`, `notify_test`\n- `backup_create`, `backup_drill`\n- `install_app`, `install_uninstall`\n- `watch_add`, `watch_check`, `watch_remove`\n- `proxmox_guest_start`, `proxmox_guest_reboot`\n\n**Destructive (4)** — ask first.\n\n- `backup_restore` — overwrites volumes with an archive\n- `docker_stop`, `install_purge` — stops a service, deletes its data\n- `proxmox_guest_shutdown`\n\n## Start here: what changed?\n\n`report` is the answer to \"how is my server doing?\" — it compares the machine\nagainst the last snapshot rather than describing the present.\n\nEach change carries a **kind**, and `--json` carries the same word, so branch on\nit rather than reading the sentence:\n\n| Kind | Means |\n| --- | --- |\n| `gone` | it was there last time and is not now |\n| `new` | it was not there last time and is now |\n| `replaced` | same name, different thing underneath — a recreated container |\n| `image` | same container, different image |\n| `state` | running where it was stopped, or the reverse |\n| `port` | same port, a different process answering on it |\n| `disk` | a mount moved by more than half a gigabyte |\n| `skipped` | the comparison could not be made — not an all-clear |\n\n```json\n{\"kind\": \"replaced\", \"target\": \"vaultwarden\",\n \"detail\": \"recreated, 4f2a1c → 9b7e03, vaultwarden:1.32 → vaultwarden:1.33\",\n \"text\": \"replaced: vaultwarden — recreated, …\"}\n```\n\n`needs_attention` and `suggested_actions` have the same shape. An action carries\n`command`, plus `runner` and `tool`:\n\n- `runner: mcp` — call `tool` and carry it out\n- `runner: cli` — homebutler can do it, no tool exposes it; the operator runs it\n- `runner: shell` — not a homebutler command at all\n\n`doctor` findings carry the same three fields. **Check `runner` before offering\nto fix something.**\n\n## What needs a shell\n\n```bash\nhomebutler init\nhomebutler trust \nhomebutler watch install\nhomebutler watch tui\nhomebutler serve --token \nhomebutler deploy --server \nhomebutler upgrade\nhomebutler notify test\nhomebutler restore \n```\n\n### `trust`, and when it is required\n\n```bash\nhomebutler trust \nhomebutler trust --reset\n```\n\nSince **0.34.0**, a server that signs in with a **password** must be trusted\nbefore the first connection: homebutler will not send a password to a host it\nhas not been told to trust, because whatever answers at that address would\nreceive it. **Key authentication still trusts on first use** — the private key\nnever leaves the machine.\n\n### `watch` supervises, `watch tui` displays\n\n```bash\nhomebutler watch add \nhomebutler watch install\nhomebutler watch tui\n```\n\n`watch` is a restart tracker: it records incidents, captures the logs from the\nmoment a container went down, and notifies. It is not a live dashboard — that is\n`watch tui`, and it is for a person rather than an agent.\n\n### `serve` edits, with a token\n\n```bash\nhomebutler serve\nhomebutler serve --token \nhomebutler serve --host 0.0.0.0 --token \n```\n\nSince **0.33.0** the dashboard edits the config file: alert thresholds,\nnotification channels, Wake-on-LAN devices, servers and Proxmox endpoints.\nWithout `--token` it is read-only and the write routes do not exist at all. The\nReport tab shows what `report` reports. There is a container image,\n`ghcr.io/higangssh/homebutler`, which reaches the machines in `servers:` over\nSSH — a container cannot see the host it runs on, and says so rather than\nanswering with its own numbers.\n\n## Notifications\n\nChannels: **telegram**, **slack**, **discord**, **webhook**, **ntfy**, **gotify**.\nntfy and Gotify are the two self-hosted push servers, and each takes its own\nshape rather than a webhook payload. Tokens travel in a header, never in a URL,\nso a failed request cannot put one in a log.\n\n```bash\nhomebutler notify test\n```\n\n`notify_test` reports each channel separately, so a failure names the channel\nthat failed rather than all of them.\n\n## Proxmox\n\nConfigured under `proxmox:` with an API token. The read credential and the one\nthat performs guest actions are separate: without an action token, start, reboot\nand shutdown are unavailable rather than falling back to the read credential.\n\n```bash\nhomebutler proxmox status\n```\n\n## Backups, and proving one comes back\n\n```bash\nhomebutler backup\nhomebutler backup list\nhomebutler backup drill \nhomebutler backup drill --all\nhomebutler restore \n```\n\n`backup drill` is the one to reach for when somebody asks whether backups are\ntrustworthy: it unpacks the archive into a container with a network and port of\nits own, starts the app on that data, and requires an HTTP health check to\nanswer.\n\n## Installing apps\n\n```bash\nhomebutler install list\nhomebutler install \nhomebutler install status \nhomebutler install uninstall \nhomebutler install purge \n```\n\n## Output and config\n\nEvery command takes `--json`. Commands that can reach another machine take\n`--server ` and `--all`.\n\nConfig is found in this order: `--config `, `$HOMEBUTLER_CONFIG`,\n`~/.config/homebutler/config.yaml`, `./homebutler.yaml`. Sections: `servers`,\n`wake`, `alerts`, `notify`, `proxmox`, `watch`, `backup`.\n\n```bash\nhomebutler config validate\n```\n\n## Prerequisites\n\n```bash\nbrew install Higangssh/homebutler/homebutler\ngo install github.com/Higangssh/homebutler@latest\n```\n\nFile v2.3.3:_meta.json\n\n{\n \"ownerId\": \"kn79fa6trrr94j7388baz1wan581qrrg\",\n \"slug\": \"homebutler\",\n \"version\": \"2.3.3\",\n \"publishedAt\": 1789564720050\n}\n\nFile v2.3.3:skill-card.md\n\n## Description:\n\nTells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[higangssh](https://clawhub.ai/user/higangssh)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators use this skill to guide an agent in checking server status, detecting meaningful changes, inspecting Docker and Proxmox resources, managing backups, and proposing or running approved Homebutler MCP tools.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can guide agents toward write or destructive server operations, including service restarts, app installation or removal, backup restore, Docker stop, and Proxmox guest shutdown.\n\nMitigation: Keep destructive tools approval-gated and require explicit confirmation before actions that restart services, install or uninstall apps, restore backups, delete data, or power-cycle guests.\n\nRisk: Using Homebutler requires trusting an external binary with access to configured servers and credentials.\n\nMitigation: Install only from trusted, pinned, or verified Homebutler releases and limit configured credentials to the access needed for intended operations.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/higangssh/skills/homebutler)\n- [Publisher profile](https://clawhub.ai/user/higangssh)\n- [Homebutler project documentation](https://github.com/Higangssh/homebutler)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, shell commands, configuration, code]\n\n**Output Format:** [Markdown with inline commands and JSON examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Guides agents to prefer MCP tools, distinguish read, write, and destructive actions, and request confirmation for destructive operations.]\n\n## Skill Version(s):\n\n2.3.3 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.3.2: 3 files, 6497 bytes\n\nFiles: skill-card.md (2558b), SKILL.md (12238b), _meta.json (129b)\n\nFile v2.3.2:SKILL.md\n\n---\nname: homebutler\ndescription: Homelab server operations via homebutler CLI/MCP. Check system status, generate butler reports, scan inventory/topology, manage Docker containers, install self-hosted apps, verify backup drills, Wake-on-LAN, port scanning, alerts, backup/restore, and multi-server SSH.\nmetadata:\n {\n \"openclaw\": {\n \"emoji\": \"🏠\",\n \"requires\": { \"anyBins\": [\"homebutler\"] },\n \"configPaths\": [\"homebutler.yaml\", \"~/.config/homebutler/config.yaml\"]\n }\n }\n---\n\n# Homebutler\n\nManage homelab servers using the [`homebutler`](https://github.com/Higangssh/homebutler) CLI. Single binary, no daemon/database required, JSON output, MCP-friendly.\n\n## Prerequisites\n\n`homebutler` must be installed and available in PATH.\n\n```bash\n# Check if installed\nwhich homebutler\n\n# Option 1: Install via Homebrew (macOS/Linux)\nbrew install Higangssh/homebutler/homebutler\n\n# Option 2: Install via Go\ngo install github.com/Higangssh/homebutler@latest\n\n# Option 3: Build from source\ngit clone https://github.com/Higangssh/homebutler.git\ncd homebutler && make build && sudo mv homebutler /usr/local/bin/\n```\n\n## Commands\n\n### Setup Wizard\n```bash\nhomebutler init # Interactive config setup\n```\nCreates a config file at `~/.config/homebutler/config.yaml` with guided prompts.\n\n### System Status\n```bash\nhomebutler status # Local server\nhomebutler status --server rpi # Specific remote server\nhomebutler status --all # All servers in parallel\n```\nReturns: hostname, OS, arch, uptime, CPU (usage%, cores), memory (total/used/%), disks (mount/total/used/%)\n\n### Butler Report\n```bash\nhomebutler report # Health, warnings, changes, suggested actions\nhomebutler report --no-save # Preview without writing a snapshot\nhomebutler report --keep 7 # Retain latest 7 snapshots\nhomebutler report --json # Structured output for automation/MCP\n```\nUse this first when the user asks “how is my homelab/server doing?” and wants a concise operational summary. It snapshots current system/container/port state and compares it with the previous run.\n\n### Inventory & Topology\n```bash\nhomebutler inventory scan # Tree view of system, containers, ports\nhomebutler inventory scan --json # Structured inventory\nhomebutler inventory export --format mermaid # Mermaid topology diagram\n```\nUse this when the user asks what is running, which container owns a port, or wants topology/context for docs or AI analysis.\n\n### Docker Management\n```bash\nhomebutler docker list # List all containers\nhomebutler docker list --server rpi # List on remote server\nhomebutler docker list --all # List on all servers\nhomebutler docker restart # Restart a container\nhomebutler docker stop # Stop a container\nhomebutler docker logs # Last 50 lines of logs\nhomebutler docker logs 200 # Last 200 lines\n```\n\n### Wake-on-LAN\n```bash\nhomebutler wake # Wake by MAC\nhomebutler wake # Wake by config name\nhomebutler wake 192.168.1.255 # Custom broadcast\n```\nConfig names are defined in config under `wake` targets.\n\n### Open Ports\n```bash\nhomebutler ports # Local\nhomebutler ports --server rpi # Remote\nhomebutler ports --all # All servers\n```\nReturns: protocol, address, port, PID, process name\n\n### Network Scan\n```bash\nhomebutler network scan\n```\nDiscovers devices on the local LAN via ping sweep + ARP table. Returns: IP, MAC, hostname, status.\nNote: May take up to 30 seconds. Some devices may not appear if they don't respond to ping.\n\n### TUI Dashboard\n```bash\nhomebutler watch # Live terminal dashboard for all servers\n```\nReal-time monitoring of all configured servers with auto-refresh. Shows CPU, memory, disk, docker containers in a terminal UI.\n\n### Web Dashboard\n```bash\nhomebutler serve # Start web dashboard on port 8080\nhomebutler serve --port 3000 # Custom port\nhomebutler serve --demo # Demo mode with fake data (no real system calls)\n```\nBrowser-based dashboard at `http://localhost:8080`. Read-only view of all servers, docker containers, alerts.\n\n### SSH Host Key Trust\n```bash\nhomebutler trust # Trust remote server's SSH host key\nhomebutler trust --reset # Remove old key and re-trust\n```\nTOFU (Trust On First Use) model. Required before first SSH connection to a new server.\n\n### Upgrade\n```bash\nhomebutler upgrade # Upgrade local + all remote servers\nhomebutler upgrade --local # Upgrade only local binary\n```\nDownloads latest release from GitHub and installs it. For remote servers, uses SSH to upgrade.\n\n### Resource Alerts\n```bash\nhomebutler alerts # Local\nhomebutler alerts --server rpi # Remote\nhomebutler alerts --all # All servers\n```\nChecks CPU/memory/disk against thresholds in config. Returns status (ok/warning/critical) per resource.\n\n### Deploy (Remote Installation)\n```bash\nhomebutler deploy --server rpi # Download from GitHub Releases\nhomebutler deploy --server rpi --local ./homebutler # Air-gapped: copy local binary\nhomebutler deploy --all # Deploy to all remote servers\n```\nInstalls homebutler on remote servers via SSH. Auto-detects remote OS/architecture.\nInstall path priority: `/usr/local/bin` → `sudo /usr/local/bin` → `~/.local/bin` (with PATH auto-registration in .profile/.bashrc/.zshrc).\n\n### App Install\n```bash\nhomebutler install list # List available apps\nhomebutler install # Install an app (docker compose)\nhomebutler install --port 9090 # Custom port\nhomebutler install status # Check app status\nhomebutler install uninstall # Stop app, keep data\nhomebutler install purge # Stop + delete all data\n```\nDeploys self-hosted apps via docker compose. Each app gets its own directory at `~/.homebutler/apps//` with auto-generated `docker-compose.yml` and persistent data. Pre-checks docker availability, port conflicts, and duplicates. Available apps include uptime-kuma, plex, vaultwarden, filebrowser, it-tools, gitea, jellyfin, homepage, stirling-pdf, speedtest-tracker, mealie, pi-hole, adguard-home, portainer, and nginx-proxy-manager.\n\n### Backup, Restore & Backup Drill\n```bash\nhomebutler backup # Back up Docker compose volumes/files\nhomebutler backup --service uptime-kuma # Back up one service\nhomebutler backup list # List backup archives\nhomebutler backup drill uptime-kuma # Boot backup in isolation and verify HTTP health\nhomebutler backup drill --all # Drill every supported app in backup\nhomebutler backup drill --archive ./file # Drill a specific archive\nhomebutler restore ./backup.tar.gz # Restore volumes from archive\n```\nPrefer `backup drill` when the user asks whether backups are trustworthy: it validates the archive, boots the app in an isolated Docker environment, health-checks it, and cleans up.\n\n### MCP Server\n```bash\nhomebutler mcp # Start MCP server (JSON-RPC over stdio)\n```\nStarts a built-in MCP (Model Context Protocol) server for use with Claude Desktop, ChatGPT, Cursor, and other MCP clients. No network ports opened — uses stdio only.\n\nCurrent MCP tools:\n- `system_status`\n- `report`\n- `inventory_scan`, `inventory_export`\n- `docker_list`, `docker_restart`, `docker_stop`, `docker_logs`, `docker_stats`\n- `wake`, `open_ports`, `network_scan`, `alerts`\n- `backup_create`, `backup_list`, `backup_drill`, `backup_restore`\n- `install_list`, `install_app`, `install_status`, `install_uninstall`, `install_purge`\n\n### Version\n```bash\nhomebutler version\n```\n\n## Output Format\n\nAll commands output human-readable text by default. Use `--json` flag for machine-parseable JSON output (recommended for AI/script integration).\n\n## Config File\n\nConfig file is auto-discovered in order:\n1. `--config ` — Explicit flag\n2. `$HOMEBUTLER_CONFIG` — Environment variable\n3. `~/.config/homebutler/config.yaml` — XDG standard (recommended)\n4. `./homebutler.yaml` — Current directory\n\nIf no config found, sensible defaults are used.\n\n### Config Options\n- `servers` — Server list with SSH connection details\n- `wake` — Named WOL targets with MAC + broadcast\n- `alerts.cpu/memory/disk` — Threshold percentages\n- `output` — Default output format\n\n### Multi-Server Config Example\n```yaml\nservers:\n - name: main-server\n host: 192.168.1.10\n local: true\n\n - name: rpi\n host: 192.168.1.20\n user: pi\n auth: key # \"key\" (default, recommended) or \"password\"\n key: ~/.ssh/id_ed25519 # optional, auto-detects\n\n - name: vps\n host: example.com\n user: deploy\n port: 2222\n auth: key\n key: ~/.ssh/id_ed25519\n```\n\n## Usage Guidelines\n\n1. **Always run commands, don't guess** — execute `homebutler status` to get real data\n2. **Interpret results for the user** — don't dump raw JSON, summarize in natural language\n3. **Warn on alerts** — if any resource shows \"warning\" or \"critical\", highlight it\n4. **Use --all for overview** — when user asks about \"all servers\" or \"everything\", use `--all`\n5. **Use --server for specific** — when user mentions a server by name, use `--server `\n6. **Docker errors** — if docker is not installed or daemon not running, explain clearly\n7. **Network scan** — warn user it may take ~30 seconds\n8. **Security** — never expose raw JSON with hostnames/IPs in group chats, summarize instead\n9. **Deploy** — suggest `--local` for air-gapped environments\n\n## Security Notes\n\n- **SSH authentication**: Always prefer key-based auth over passwords. Never store plaintext passwords in config.\n- **Network scans**: Only run on your own local network. Warn user before scanning.\n- **Deploy**: Only deploy to servers you own. Confirm with user before remote installations.\n- **Config file permissions**: Keep config files readable only by owner (`chmod 600`).\n- **No telemetry**: homebutler sends zero data externally. All operations are local or to user-configured hosts only.\n\n## Error Handling\n\n- **SSH connection failed** → Check host/port/user in config, verify SSH key is registered on remote\n- **homebutler not found on remote** → Run `homebutler deploy --server ` first\n- **docker not installed** → Tell user docker is not available on that server\n- **docker daemon not running** → Suggest `sudo systemctl start docker`\n- **network scan timeout** → Normal on large subnets, suggest retrying\n- **permission denied** → May need sudo for ports/docker commands on some systems\n\n## Example Interactions\n\nUser: \"How's the server doing?\"\n→ Prefer `homebutler report`, summarize health, warnings, notable changes, and suggested actions. Use `homebutler status` only for a raw point-in-time status.\n\nUser: \"What changed / what owns this port / map my homelab\"\n→ Run `homebutler inventory scan` or `homebutler inventory export --format mermaid`.\n\nUser: \"Check all servers\"\n→ Run `homebutler status --all`, summarize each server's status\n\nUser: \"How's the Raspberry Pi?\"\n→ Run `homebutler status --server rpi`, summarize\n\nUser: \"What docker containers are running?\"\n→ Run `homebutler docker list`, list container names and states\n\nUser: \"Wake up the NAS\"\n→ Run `homebutler wake nas` (if configured) or ask for MAC address\n\nUser: \"Any alerts across all servers?\"\n→ Run `homebutler alerts --all`, report any warnings/critical\n\nUser: \"Deploy homebutler to the new server\"\n→ Run `homebutler deploy --server `, report result\n\nUser: \"Install uptime-kuma\"\n→ Run `homebutler install uptime-kuma`, report URL and status\n\nUser: \"What apps are available?\"\n→ Run `homebutler install list`, show available apps\n\nUser: \"Remove vaultwarden completely\"\n→ Run `homebutler install purge vaultwarden`, confirm deletion\n\nUser: \"Can I trust my backup?\"\n→ Run `homebutler backup drill ` or `homebutler backup drill --all`, report pass/fail and health status\n\nFile v2.3.2:_meta.json\n\n{\n \"ownerId\": \"kn79fa6trrr94j7388baz1wan581qrrg\",\n \"slug\": \"homebutler\",\n \"version\": \"2.3.2\",\n \"publishedAt\": 1777781110637\n}\n\nFile v2.3.2:skill-card.md\n\n## Description:\n\nHomebutler enables homelab server operations through the homebutler CLI and MCP, including status reporting, inventory and topology scans, Docker management, self-hosted app installation, backup and restore workflows, Wake-on-LAN, port scans, alerts, and multi-server SSH.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[higangssh](https://clawhub.ai/user/higangssh)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, operators, and homelab administrators use this skill to let an agent inspect, summarize, and administer local or configured remote servers. It is intended for operational tasks such as checking health, managing containers, deploying self-hosted apps, validating backups, and explaining alerts.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can guide an agent through broad local and remote homelab administration, including SSH-based operations and Docker management.\n\nMitigation: Install only when you trust the upstream project, review configured SSH access and config file permissions, and limit the agent to servers you intend it to administer.\n\nRisk: Deploy, upgrade, restore, purge, Docker stop/restart, and --all operations can change or remove services across one or more systems.\n\nMitigation: Require explicit user confirmation before these operations and prefer scoped server or service targets over broad all-server commands.\n\nRisk: Install and upgrade flows may fetch or place binaries in system-wide paths.\n\nMitigation: Pin or verify releases before installation and avoid sudo or system-wide installation paths when a user-local path is sufficient.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/higangssh/skills/homebutler)\n- [Publisher profile](https://clawhub.ai/user/higangssh)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with inline shell commands, command summaries, and optional JSON-oriented guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [The skill expects the homebutler binary in PATH and may refer to homebutler.yaml or ~/.config/homebutler/config.yaml.]\n\n## Skill Version(s):\n\n2.3.2 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.18.1: 2 files, 5137 bytes\n\nFiles: SKILL.md (12238b), _meta.json (130b)\n\nFile v0.18.1:SKILL.md\n\n---\nname: homebutler\ndescription: Homelab server operations via homebutler CLI/MCP. Check system status, generate butler reports, scan inventory/topology, manage Docker containers, install self-hosted apps, verify backup drills, Wake-on-LAN, port scanning, alerts, backup/restore, and multi-server SSH.\nmetadata:\n {\n \"openclaw\": {\n \"emoji\": \"🏠\",\n \"requires\": { \"anyBins\": [\"homebutler\"] },\n \"configPaths\": [\"homebutler.yaml\", \"~/.config/homebutler/config.yaml\"]\n }\n }\n---\n\n# Homebutler\n\nManage homelab servers using the [`homebutler`](https://github.com/Higangssh/homebutler) CLI. Single binary, no daemon/database required, JSON output, MCP-friendly.\n\n## Prerequisites\n\n`homebutler` must be installed and available in PATH.\n\n```bash\n# Check if installed\nwhich homebutler\n\n# Option 1: Install via Homebrew (macOS/Linux)\nbrew install Higangssh/homebutler/homebutler\n\n# Option 2: Install via Go\ngo install github.com/Higangssh/homebutler@latest\n\n# Option 3: Build from source\ngit clone https://github.com/Higangssh/homebutler.git\ncd homebutler && make build && sudo mv homebutler /usr/local/bin/\n```\n\n## Commands\n\n### Setup Wizard\n```bash\nhomebutler init # Interactive config setup\n```\nCreates a config file at `~/.config/homebutler/config.yaml` with guided prompts.\n\n### System Status\n```bash\nhomebutler status # Local server\nhomebutler status --server rpi # Specific remote server\nhomebutler status --all # All servers in parallel\n```\nReturns: hostname, OS, arch, uptime, CPU (usage%, cores), memory (total/used/%), disks (mount/total/used/%)\n\n### Butler Report\n```bash\nhomebutler report # Health, warnings, changes, suggested actions\nhomebutler report --no-save # Preview without writing a snapshot\nhomebutler report --keep 7 # Retain latest 7 snapshots\nhomebutler report --json # Structured output for automation/MCP\n```\nUse this first when the user asks “how is my homelab/server doing?” and wants a concise operational summary. It snapshots current system/container/port state and compares it with the previous run.\n\n### Inventory & Topology\n```bash\nhomebutler inventory scan # Tree view of system, containers, ports\nhomebutler inventory scan --json # Structured inventory\nhomebutler inventory export --format mermaid # Mermaid topology diagram\n```\nUse this when the user asks what is running, which container owns a port, or wants topology/context for docs or AI analysis.\n\n### Docker Management\n```bash\nhomebutler docker list # List all containers\nhomebutler docker list --server rpi # List on remote server\nhomebutler docker list --all # List on all servers\nhomebutler docker restart # Restart a container\nhomebutler docker stop # Stop a container\nhomebutler docker logs # Last 50 lines of logs\nhomebutler docker logs 200 # Last 200 lines\n```\n\n### Wake-on-LAN\n```bash\nhomebutler wake # Wake by MAC\nhomebutler wake # Wake by config name\nhomebutler wake 192.168.1.255 # Custom broadcast\n```\nConfig names are defined in config under `wake` targets.\n\n### Open Ports\n```bash\nhomebutler ports # Local\nhomebutler ports --server rpi # Remote\nhomebutler ports --all # All servers\n```\nReturns: protocol, address, port, PID, process name\n\n### Network Scan\n```bash\nhomebutler network scan\n```\nDiscovers devices on the local LAN via ping sweep + ARP table. Returns: IP, MAC, hostname, status.\nNote: May take up to 30 seconds. Some devices may not appear if they don't respond to ping.\n\n### TUI Dashboard\n```bash\nhomebutler watch # Live terminal dashboard for all servers\n```\nReal-time monitoring of all configured servers with auto-refresh. Shows CPU, memory, disk, docker containers in a terminal UI.\n\n### Web Dashboard\n```bash\nhomebutler serve # Start web dashboard on port 8080\nhomebutler serve --port 3000 # Custom port\nhomebutler serve --demo # Demo mode with fake data (no real system calls)\n```\nBrowser-based dashboard at `http://localhost:8080`. Read-only view of all servers, docker containers, alerts.\n\n### SSH Host Key Trust\n```bash\nhomebutler trust # Trust remote server's SSH host key\nhomebutler trust --reset # Remove old key and re-trust\n```\nTOFU (Trust On First Use) model. Required before first SSH connection to a new server.\n\n### Upgrade\n```bash\nhomebutler upgrade # Upgrade local + all remote servers\nhomebutler upgrade --local # Upgrade only local binary\n```\nDownloads latest release from GitHub and installs it. For remote servers, uses SSH to upgrade.\n\n### Resource Alerts\n```bash\nhomebutler alerts # Local\nhomebutler alerts --server rpi # Remote\nhomebutler alerts --all # All servers\n```\nChecks CPU/memory/disk against thresholds in config. Returns status (ok/warning/critical) per resource.\n\n### Deploy (Remote Installation)\n```bash\nhomebutler deploy --server rpi # Download from GitHub Releases\nhomebutler deploy --server rpi --local ./homebutler # Air-gapped: copy local binary\nhomebutler deploy --all # Deploy to all remote servers\n```\nInstalls homebutler on remote servers via SSH. Auto-detects remote OS/architecture.\nInstall path priority: `/usr/local/bin` → `sudo /usr/local/bin` → `~/.local/bin` (with PATH auto-registration in .profile/.bashrc/.zshrc).\n\n### App Install\n```bash\nhomebutler install list # List available apps\nhomebutler install # Install an app (docker compose)\nhomebutler install --port 9090 # Custom port\nhomebutler install status # Check app status\nhomebutler install uninstall # Stop app, keep data\nhomebutler install purge # Stop + delete all data\n```\nDeploys self-hosted apps via docker compose. Each app gets its own directory at `~/.homebutler/apps//` with auto-generated `docker-compose.yml` and persistent data. Pre-checks docker availability, port conflicts, and duplicates. Available apps include uptime-kuma, plex, vaultwarden, filebrowser, it-tools, gitea, jellyfin, homepage, stirling-pdf, speedtest-tracker, mealie, pi-hole, adguard-home, portainer, and nginx-proxy-manager.\n\n### Backup, Restore & Backup Drill\n```bash\nhomebutler backup # Back up Docker compose volumes/files\nhomebutler backup --service uptime-kuma # Back up one service\nhomebutler backup list # List backup archives\nhomebutler backup drill uptime-kuma # Boot backup in isolation and verify HTTP health\nhomebutler backup drill --all # Drill every supported app in backup\nhomebutler backup drill --archive ./file # Drill a specific archive\nhomebutler restore ./backup.tar.gz # Restore volumes from archive\n```\nPrefer `backup drill` when the user asks whether backups are trustworthy: it validates the archive, boots the app in an isolated Docker environment, health-checks it, and cleans up.\n\n### MCP Server\n```bash\nhomebutler mcp # Start MCP server (JSON-RPC over stdio)\n```\nStarts a built-in MCP (Model Context Protocol) server for use with Claude Desktop, ChatGPT, Cursor, and other MCP clients. No network ports opened — uses stdio only.\n\nCurrent MCP tools:\n- `system_status`\n- `report`\n- `inventory_scan`, `inventory_export`\n- `docker_list`, `docker_restart`, `docker_stop`, `docker_logs`, `docker_stats`\n- `wake`, `open_ports`, `network_scan`, `alerts`\n- `backup_create`, `backup_list`, `backup_drill`, `backup_restore`\n- `install_list`, `install_app`, `install_status`, `install_uninstall`, `install_purge`\n\n### Version\n```bash\nhomebutler version\n```\n\n## Output Format\n\nAll commands output human-readable text by default. Use `--json` flag for machine-parseable JSON output (recommended for AI/script integration).\n\n## Config File\n\nConfig file is auto-discovered in order:\n1. `--config ` — Explicit flag\n2. `$HOMEBUTLER_CONFIG` — Environment variable\n3. `~/.config/homebutler/config.yaml` — XDG standard (recommended)\n4. `./homebutler.yaml` — Current directory\n\nIf no config found, sensible defaults are used.\n\n### Config Options\n- `servers` — Server list with SSH connection details\n- `wake` — Named WOL targets with MAC + broadcast\n- `alerts.cpu/memory/disk` — Threshold percentages\n- `output` — Default output format\n\n### Multi-Server Config Example\n```yaml\nservers:\n - name: main-server\n host: 192.168.1.10\n local: true\n\n - name: rpi\n host: 192.168.1.20\n user: pi\n auth: key # \"key\" (default, recommended) or \"password\"\n key: ~/.ssh/id_ed25519 # optional, auto-detects\n\n - name: vps\n host: example.com\n user: deploy\n port: 2222\n auth: key\n key: ~/.ssh/id_ed25519\n```\n\n## Usage Guidelines\n\n1. **Always run commands, don't guess** — execute `homebutler status` to get real data\n2. **Interpret results for the user** — don't dump raw JSON, summarize in natural language\n3. **Warn on alerts** — if any resource shows \"warning\" or \"critical\", highlight it\n4. **Use --all for overview** — when user asks about \"all servers\" or \"everything\", use `--all`\n5. **Use --server for specific** — when user mentions a server by name, use `--server `\n6. **Docker errors** — if docker is not installed or daemon not running, explain clearly\n7. **Network scan** — warn user it may take ~30 seconds\n8. **Security** — never expose raw JSON with hostnames/IPs in group chats, summarize instead\n9. **Deploy** — suggest `--local` for air-gapped environments\n\n## Security Notes\n\n- **SSH authentication**: Always prefer key-based auth over passwords. Never store plaintext passwords in config.\n- **Network scans**: Only run on your own local network. Warn user before scanning.\n- **Deploy**: Only deploy to servers you own. Confirm with user before remote installations.\n- **Config file permissions**: Keep config files readable only by owner (`chmod 600`).\n- **No telemetry**: homebutler sends zero data externally. All operations are local or to user-configured hosts only.\n\n## Error Handling\n\n- **SSH connection failed** → Check host/port/user in config, verify SSH key is registered on remote\n- **homebutler not found on remote** → Run `homebutler deploy --server ` first\n- **docker not installed** → Tell user docker is not available on that server\n- **docker daemon not running** → Suggest `sudo systemctl start docker`\n- **network scan timeout** → Normal on large subnets, suggest retrying\n- **permission denied** → May need sudo for ports/docker commands on some systems\n\n## Example Interactions\n\nUser: \"How's the server doing?\"\n→ Prefer `homebutler report`, summarize health, warnings, notable changes, and suggested actions. Use `homebutler status` only for a raw point-in-time status.\n\nUser: \"What changed / what owns this port / map my homelab\"\n→ Run `homebutler inventory scan` or `homebutler inventory export --format mermaid`.\n\nUser: \"Check all servers\"\n→ Run `homebutler status --all`, summarize each server's status\n\nUser: \"How's the Raspberry Pi?\"\n→ Run `homebutler status --server rpi`, summarize\n\nUser: \"What docker containers are running?\"\n→ Run `homebutler docker list`, list container names and states\n\nUser: \"Wake up the NAS\"\n→ Run `homebutler wake nas` (if configured) or ask for MAC address\n\nUser: \"Any alerts across all servers?\"\n→ Run `homebutler alerts --all`, report any warnings/critical\n\nUser: \"Deploy homebutler to the new server\"\n→ Run `homebutler deploy --server `, report result\n\nUser: \"Install uptime-kuma\"\n→ Run `homebutler install uptime-kuma`, report URL and status\n\nUser: \"What apps are available?\"\n→ Run `homebutler install list`, show available apps\n\nUser: \"Remove vaultwarden completely\"\n→ Run `homebutler install purge vaultwarden`, confirm deletion\n\nUser: \"Can I trust my backup?\"\n→ Run `homebutler backup drill ` or `homebutler backup drill --all`, report pass/fail and health status\n\nFile v0.18.1:_meta.json\n\n{\n \"ownerId\": \"kn79fa6trrr94j7388baz1wan581qrrg\",\n \"slug\": \"homebutler\",\n \"version\": \"0.18.1\",\n \"publishedAt\": 1777780219211\n}\n\nArchive v2.3.1: 2 files, 5135 bytes\n\nFiles: SKILL.md (12238b), _meta.json (129b)\n\nFile v2.3.1:SKILL.md\n\n---\nname: homebutler\ndescription: Homelab server operations via homebutler CLI/MCP. Check system status, generate butler reports, scan inventory/topology, manage Docker containers, install self-hosted apps, verify backup drills, Wake-on-LAN, port scanning, alerts, backup/restore, and multi-server SSH.\nmetadata:\n {\n \"openclaw\": {\n \"emoji\": \"🏠\",\n \"requires\": { \"anyBins\": [\"homebutler\"] },\n \"configPaths\": [\"homebutler.yaml\", \"~/.config/homebutler/config.yaml\"]\n }\n }\n---\n\n# homebutler\n\nManage homelab servers using the [`homebutler`](https://github.com/Higangssh/homebutler) CLI. Single binary, no daemon/database required, JSON output, MCP-friendly.\n\n## Prerequisites\n\n`homebutler` must be installed and available in PATH.\n\n```bash\n# Check if installed\nwhich homebutler\n\n# Option 1: Install via Homebrew (macOS/Linux)\nbrew install Higangssh/homebutler/homebutler\n\n# Option 2: Install via Go\ngo install github.com/Higangssh/homebutler@latest\n\n# Option 3: Build from source\ngit clone https://github.com/Higangssh/homebutler.git\ncd homebutler && make build && sudo mv homebutler /usr/local/bin/\n```\n\n## Commands\n\n### Setup Wizard\n```bash\nhomebutler init # Interactive config setup\n```\nCreates a config file at `~/.config/homebutler/config.yaml` with guided prompts.\n\n### System Status\n```bash\nhomebutler status # Local server\nhomebutler status --server rpi # Specific remote server\nhomebutler status --all # All servers in parallel\n```\nReturns: hostname, OS, arch, uptime, CPU (usage%, cores), memory (total/used/%), disks (mount/total/used/%)\n\n### Butler Report\n```bash\nhomebutler report # Health, warnings, changes, suggested actions\nhomebutler report --no-save # Preview without writing a snapshot\nhomebutler report --keep 7 # Retain latest 7 snapshots\nhomebutler report --json # Structured output for automation/MCP\n```\nUse this first when the user asks “how is my homelab/server doing?” and wants a concise operational summary. It snapshots current system/container/port state and compares it with the previous run.\n\n### Inventory & Topology\n```bash\nhomebutler inventory scan # Tree view of system, containers, ports\nhomebutler inventory scan --json # Structured inventory\nhomebutler inventory export --format mermaid # Mermaid topology diagram\n```\nUse this when the user asks what is running, which container owns a port, or wants topology/context for docs or AI analysis.\n\n### Docker Management\n```bash\nhomebutler docker list # List all containers\nhomebutler docker list --server rpi # List on remote server\nhomebutler docker list --all # List on all servers\nhomebutler docker restart # Restart a container\nhomebutler docker stop # Stop a container\nhomebutler docker logs # Last 50 lines of logs\nhomebutler docker logs 200 # Last 200 lines\n```\n\n### Wake-on-LAN\n```bash\nhomebutler wake # Wake by MAC\nhomebutler wake # Wake by config name\nhomebutler wake 192.168.1.255 # Custom broadcast\n```\nConfig names are defined in config under `wake` targets.\n\n### Open Ports\n```bash\nhomebutler ports # Local\nhomebutler ports --server rpi # Remote\nhomebutler ports --all # All servers\n```\nReturns: protocol, address, port, PID, process name\n\n### Network Scan\n```bash\nhomebutler network scan\n```\nDiscovers devices on the local LAN via ping sweep + ARP table. Returns: IP, MAC, hostname, status.\nNote: May take up to 30 seconds. Some devices may not appear if they don't respond to ping.\n\n### TUI Dashboard\n```bash\nhomebutler watch # Live terminal dashboard for all servers\n```\nReal-time monitoring of all configured servers with auto-refresh. Shows CPU, memory, disk, docker containers in a terminal UI.\n\n### Web Dashboard\n```bash\nhomebutler serve # Start web dashboard on port 8080\nhomebutler serve --port 3000 # Custom port\nhomebutler serve --demo # Demo mode with fake data (no real system calls)\n```\nBrowser-based dashboard at `http://localhost:8080`. Read-only view of all servers, docker containers, alerts.\n\n### SSH Host Key Trust\n```bash\nhomebutler trust # Trust remote server's SSH host key\nhomebutler trust --reset # Remove old key and re-trust\n```\nTOFU (Trust On First Use) model. Required before first SSH connection to a new server.\n\n### Upgrade\n```bash\nhomebutler upgrade # Upgrade local + all remote servers\nhomebutler upgrade --local # Upgrade only local binary\n```\nDownloads latest release from GitHub and installs it. For remote servers, uses SSH to upgrade.\n\n### Resource Alerts\n```bash\nhomebutler alerts # Local\nhomebutler alerts --server rpi # Remote\nhomebutler alerts --all # All servers\n```\nChecks CPU/memory/disk against thresholds in config. Returns status (ok/warning/critical) per resource.\n\n### Deploy (Remote Installation)\n```bash\nhomebutler deploy --server rpi # Download from GitHub Releases\nhomebutler deploy --server rpi --local ./homebutler # Air-gapped: copy local binary\nhomebutler deploy --all # Deploy to all remote servers\n```\nInstalls homebutler on remote servers via SSH. Auto-detects remote OS/architecture.\nInstall path priority: `/usr/local/bin` → `sudo /usr/local/bin` → `~/.local/bin` (with PATH auto-registration in .profile/.bashrc/.zshrc).\n\n### App Install\n```bash\nhomebutler install list # List available apps\nhomebutler install # Install an app (docker compose)\nhomebutler install --port 9090 # Custom port\nhomebutler install status # Check app status\nhomebutler install uninstall # Stop app, keep data\nhomebutler install purge # Stop + delete all data\n```\nDeploys self-hosted apps via docker compose. Each app gets its own directory at `~/.homebutler/apps//` with auto-generated `docker-compose.yml` and persistent data. Pre-checks docker availability, port conflicts, and duplicates. Available apps include uptime-kuma, plex, vaultwarden, filebrowser, it-tools, gitea, jellyfin, homepage, stirling-pdf, speedtest-tracker, mealie, pi-hole, adguard-home, portainer, and nginx-proxy-manager.\n\n### Backup, Restore & Backup Drill\n```bash\nhomebutler backup # Back up Docker compose volumes/files\nhomebutler backup --service uptime-kuma # Back up one service\nhomebutler backup list # List backup archives\nhomebutler backup drill uptime-kuma # Boot backup in isolation and verify HTTP health\nhomebutler backup drill --all # Drill every supported app in backup\nhomebutler backup drill --archive ./file # Drill a specific archive\nhomebutler restore ./backup.tar.gz # Restore volumes from archive\n```\nPrefer `backup drill` when the user asks whether backups are trustworthy: it validates the archive, boots the app in an isolated Docker environment, health-checks it, and cleans up.\n\n### MCP Server\n```bash\nhomebutler mcp # Start MCP server (JSON-RPC over stdio)\n```\nStarts a built-in MCP (Model Context Protocol) server for use with Claude Desktop, ChatGPT, Cursor, and other MCP clients. No network ports opened — uses stdio only.\n\nCurrent MCP tools:\n- `system_status`\n- `report`\n- `inventory_scan`, `inventory_export`\n- `docker_list`, `docker_restart`, `docker_stop`, `docker_logs`, `docker_stats`\n- `wake`, `open_ports`, `network_scan`, `alerts`\n- `backup_create`, `backup_list`, `backup_drill`, `backup_restore`\n- `install_list`, `install_app`, `install_status`, `install_uninstall`, `install_purge`\n\n### Version\n```bash\nhomebutler version\n```\n\n## Output Format\n\nAll commands output human-readable text by default. Use `--json` flag for machine-parseable JSON output (recommended for AI/script integration).\n\n## Config File\n\nConfig file is auto-discovered in order:\n1. `--config ` — Explicit flag\n2. `$HOMEBUTLER_CONFIG` — Environment variable\n3. `~/.config/homebutler/config.yaml` — XDG standard (recommended)\n4. `./homebutler.yaml` — Current directory\n\nIf no config found, sensible defaults are used.\n\n### Config Options\n- `servers` — Server list with SSH connection details\n- `wake` — Named WOL targets with MAC + broadcast\n- `alerts.cpu/memory/disk` — Threshold percentages\n- `output` — Default output format\n\n### Multi-Server Config Example\n```yaml\nservers:\n - name: main-server\n host: 192.168.1.10\n local: true\n\n - name: rpi\n host: 192.168.1.20\n user: pi\n auth: key # \"key\" (default, recommended) or \"password\"\n key: ~/.ssh/id_ed25519 # optional, auto-detects\n\n - name: vps\n host: example.com\n user: deploy\n port: 2222\n auth: key\n key: ~/.ssh/id_ed25519\n```\n\n## Usage Guidelines\n\n1. **Always run commands, don't guess** — execute `homebutler status` to get real data\n2. **Interpret results for the user** — don't dump raw JSON, summarize in natural language\n3. **Warn on alerts** — if any resource shows \"warning\" or \"critical\", highlight it\n4. **Use --all for overview** — when user asks about \"all servers\" or \"everything\", use `--all`\n5. **Use --server for specific** — when user mentions a server by name, use `--server `\n6. **Docker errors** — if docker is not installed or daemon not running, explain clearly\n7. **Network scan** — warn user it may take ~30 seconds\n8. **Security** — never expose raw JSON with hostnames/IPs in group chats, summarize instead\n9. **Deploy** — suggest `--local` for air-gapped environments\n\n## Security Notes\n\n- **SSH authentication**: Always prefer key-based auth over passwords. Never store plaintext passwords in config.\n- **Network scans**: Only run on your own local network. Warn user before scanning.\n- **Deploy**: Only deploy to servers you own. Confirm with user before remote installations.\n- **Config file permissions**: Keep config files readable only by owner (`chmod 600`).\n- **No telemetry**: homebutler sends zero data externally. All operations are local or to user-configured hosts only.\n\n## Error Handling\n\n- **SSH connection failed** → Check host/port/user in config, verify SSH key is registered on remote\n- **homebutler not found on remote** → Run `homebutler deploy --server ` first\n- **docker not installed** → Tell user docker is not available on that server\n- **docker daemon not running** → Suggest `sudo systemctl start docker`\n- **network scan timeout** → Normal on large subnets, suggest retrying\n- **permission denied** → May need sudo for ports/docker commands on some systems\n\n## Example Interactions\n\nUser: \"How's the server doing?\"\n→ Prefer `homebutler report`, summarize health, warnings, notable changes, and suggested actions. Use `homebutler status` only for a raw point-in-time status.\n\nUser: \"What changed / what owns this port / map my homelab\"\n→ Run `homebutler inventory scan` or `homebutler inventory export --format mermaid`.\n\nUser: \"Check all servers\"\n→ Run `homebutler status --all`, summarize each server's status\n\nUser: \"How's the Raspberry Pi?\"\n→ Run `homebutler status --server rpi`, summarize\n\nUser: \"What docker containers are running?\"\n→ Run `homebutler docker list`, list container names and states\n\nUser: \"Wake up the NAS\"\n→ Run `homebutler wake nas` (if configured) or ask for MAC address\n\nUser: \"Any alerts across all servers?\"\n→ Run `homebutler alerts --all`, report any warnings/critical\n\nUser: \"Deploy homebutler to the new server\"\n→ Run `homebutler deploy --server `, report result\n\nUser: \"Install uptime-kuma\"\n→ Run `homebutler install uptime-kuma`, report URL and status\n\nUser: \"What apps are available?\"\n→ Run `homebutler install list`, show available apps\n\nUser: \"Remove vaultwarden completely\"\n→ Run `homebutler install purge vaultwarden`, confirm deletion\n\nUser: \"Can I trust my backup?\"\n→ Run `homebutler backup drill ` or `homebutler backup drill --all`, report pass/fail and health status\n\nFile v2.3.1:_meta.json\n\n{\n \"ownerId\": \"kn79fa6trrr94j7388baz1wan581qrrg\",\n \"slug\": \"homebutler\",\n \"version\": \"2.3.1\",\n \"publishedAt\": 1777779917618\n}\n\nArchive v2.3.0: 2 files, 5141 bytes\n\nFiles: SKILL.md (12249b), _meta.json (129b)\n\nFile v2.3.0:SKILL.md\n\n---\nname: homebutler\ndescription: Homelab server operations via homebutler CLI/MCP. Check system status, generate butler reports, scan inventory/topology, manage Docker containers, install self-hosted apps, verify backup drills, Wake-on-LAN, port scanning, alerts, backup/restore, and multi-server SSH.\nmetadata:\n {\n \"openclaw\": {\n \"emoji\": \"🏠\",\n \"requires\": { \"anyBins\": [\"homebutler\"] },\n \"configPaths\": [\"homebutler.yaml\", \"~/.config/homebutler/config.yaml\"]\n }\n }\n---\n\n# Homeserver Management\n\nManage homelab servers using the [`homebutler`](https://github.com/Higangssh/homebutler) CLI. Single binary, no daemon/database required, JSON output, MCP-friendly.\n\n## Prerequisites\n\n`homebutler` must be installed and available in PATH.\n\n```bash\n# Check if installed\nwhich homebutler\n\n# Option 1: Install via Homebrew (macOS/Linux)\nbrew install Higangssh/homebutler/homebutler\n\n# Option 2: Install via Go\ngo install github.com/Higangssh/homebutler@latest\n\n# Option 3: Build from source\ngit clone https://github.com/Higangssh/homebutler.git\ncd homebutler && make build && sudo mv homebutler /usr/local/bin/\n```\n\n## Commands\n\n### Setup Wizard\n```bash\nhomebutler init # Interactive config setup\n```\nCreates a config file at `~/.config/homebutler/config.yaml` with guided prompts.\n\n### System Status\n```bash\nhomebutler status # Local server\nhomebutler status --server rpi # Specific remote server\nhomebutler status --all # All servers in parallel\n```\nReturns: hostname, OS, arch, uptime, CPU (usage%, cores), memory (total/used/%), disks (mount/total/used/%)\n\n### Butler Report\n```bash\nhomebutler report # Health, warnings, changes, suggested actions\nhomebutler report --no-save # Preview without writing a snapshot\nhomebutler report --keep 7 # Retain latest 7 snapshots\nhomebutler report --json # Structured output for automation/MCP\n```\nUse this first when the user asks “how is my homelab/server doing?” and wants a concise operational summary. It snapshots current system/container/port state and compares it with the previous run.\n\n### Inventory & Topology\n```bash\nhomebutler inventory scan # Tree view of system, containers, ports\nhomebutler inventory scan --json # Structured inventory\nhomebutler inventory export --format mermaid # Mermaid topology diagram\n```\nUse this when the user asks what is running, which container owns a port, or wants topology/context for docs or AI analysis.\n\n### Docker Management\n```bash\nhomebutler docker list # List all containers\nhomebutler docker list --server rpi # List on remote server\nhomebutler docker list --all # List on all servers\nhomebutler docker restart # Restart a container\nhomebutler docker stop # Stop a container\nhomebutler docker logs # Last 50 lines of logs\nhomebutler docker logs 200 # Last 200 lines\n```\n\n### Wake-on-LAN\n```bash\nhomebutler wake # Wake by MAC\nhomebutler wake # Wake by config name\nhomebutler wake 192.168.1.255 # Custom broadcast\n```\nConfig names are defined in config under `wake` targets.\n\n### Open Ports\n```bash\nhomebutler ports # Local\nhomebutler ports --server rpi # Remote\nhomebutler ports --all # All servers\n```\nReturns: protocol, address, port, PID, process name\n\n### Network Scan\n```bash\nhomebutler network scan\n```\nDiscovers devices on the local LAN via ping sweep + ARP table. Returns: IP, MAC, hostname, status.\nNote: May take up to 30 seconds. Some devices may not appear if they don't respond to ping.\n\n### TUI Dashboard\n```bash\nhomebutler watch # Live terminal dashboard for all servers\n```\nReal-time monitoring of all configured servers with auto-refresh. Shows CPU, memory, disk, docker containers in a terminal UI.\n\n### Web Dashboard\n```bash\nhomebutler serve # Start web dashboard on port 8080\nhomebutler serve --port 3000 # Custom port\nhomebutler serve --demo # Demo mode with fake data (no real system calls)\n```\nBrowser-based dashboard at `http://localhost:8080`. Read-only view of all servers, docker containers, alerts.\n\n### SSH Host Key Trust\n```bash\nhomebutler trust # Trust remote server's SSH host key\nhomebutler trust --reset # Remove old key and re-trust\n```\nTOFU (Trust On First Use) model. Required before first SSH connection to a new server.\n\n### Upgrade\n```bash\nhomebutler upgrade # Upgrade local + all remote servers\nhomebutler upgrade --local # Upgrade only local binary\n```\nDownloads latest release from GitHub and installs it. For remote servers, uses SSH to upgrade.\n\n### Resource Alerts\n```bash\nhomebutler alerts # Local\nhomebutler alerts --server rpi # Remote\nhomebutler alerts --all # All servers\n```\nChecks CPU/memory/disk against thresholds in config. Returns status (ok/warning/critical) per resource.\n\n### Deploy (Remote Installation)\n```bash\nhomebutler deploy --server rpi # Download from GitHub Releases\nhomebutler deploy --server rpi --local ./homebutler # Air-gapped: copy local binary\nhomebutler deploy --all # Deploy to all remote servers\n```\nInstalls homebutler on remote servers via SSH. Auto-detects remote OS/architecture.\nInstall path priority: `/usr/local/bin` → `sudo /usr/local/bin` → `~/.local/bin` (with PATH auto-registration in .profile/.bashrc/.zshrc).\n\n### App Install\n```bash\nhomebutler install list # List available apps\nhomebutler install # Install an app (docker compose)\nhomebutler install --port 9090 # Custom port\nhomebutler install status # Check app status\nhomebutler install uninstall # Stop app, keep data\nhomebutler install purge # Stop + delete all data\n```\nDeploys self-hosted apps via docker compose. Each app gets its own directory at `~/.homebutler/apps//` with auto-generated `docker-compose.yml` and persistent data. Pre-checks docker availability, port conflicts, and duplicates. Available apps include uptime-kuma, plex, vaultwarden, filebrowser, it-tools, gitea, jellyfin, homepage, stirling-pdf, speedtest-tracker, mealie, pi-hole, adguard-home, portainer, and nginx-proxy-manager.\n\n### Backup, Restore & Backup Drill\n```bash\nhomebutler backup # Back up Docker compose volumes/files\nhomebutler backup --service uptime-kuma # Back up one service\nhomebutler backup list # List backup archives\nhomebutler backup drill uptime-kuma # Boot backup in isolation and verify HTTP health\nhomebutler backup drill --all # Drill every supported app in backup\nhomebutler backup drill --archive ./file # Drill a specific archive\nhomebutler restore ./backup.tar.gz # Restore volumes from archive\n```\nPrefer `backup drill` when the user asks whether backups are trustworthy: it validates the archive, boots the app in an isolated Docker environment, health-checks it, and cleans up.\n\n### MCP Server\n```bash\nhomebutler mcp # Start MCP server (JSON-RPC over stdio)\n```\nStarts a built-in MCP (Model Context Protocol) server for use with Claude Desktop, ChatGPT, Cursor, and other MCP clients. No network ports opened — uses stdio only.\n\nCurrent MCP tools:\n- `system_status`\n- `report`\n- `inventory_scan`, `inventory_export`\n- `docker_list`, `docker_restart`, `docker_stop`, `docker_logs`, `docker_stats`\n- `wake`, `open_ports`, `network_scan`, `alerts`\n- `backup_create`, `backup_list`, `backup_drill`, `backup_restore`\n- `install_list`, `install_app`, `install_status`, `install_uninstall`, `install_purge`\n\n### Version\n```bash\nhomebutler version\n```\n\n## Output Format\n\nAll commands output human-readable text by default. Use `--json` flag for machine-parseable JSON output (recommended for AI/script integration).\n\n## Config File\n\nConfig file is auto-discovered in order:\n1. `--config ` — Explicit flag\n2. `$HOMEBUTLER_CONFIG` — Environment variable\n3. `~/.config/homebutler/config.yaml` — XDG standard (recommended)\n4. `./homebutler.yaml` — Current directory\n\nIf no config found, sensible defaults are used.\n\n### Config Options\n- `servers` — Server list with SSH connection details\n- `wake` — Named WOL targets with MAC + broadcast\n- `alerts.cpu/memory/disk` — Threshold percentages\n- `output` — Default output format\n\n### Multi-Server Config Example\n```yaml\nservers:\n - name: main-server\n host: 192.168.1.10\n local: true\n\n - name: rpi\n host: 192.168.1.20\n user: pi\n auth: key # \"key\" (default, recommended) or \"password\"\n key: ~/.ssh/id_ed25519 # optional, auto-detects\n\n - name: vps\n host: example.com\n user: deploy\n port: 2222\n auth: key\n key: ~/.ssh/id_ed25519\n```\n\n## Usage Guidelines\n\n1. **Always run commands, don't guess** — execute `homebutler status` to get real data\n2. **Interpret results for the user** — don't dump raw JSON, summarize in natural language\n3. **Warn on alerts** — if any resource shows \"warning\" or \"critical\", highlight it\n4. **Use --all for overview** — when user asks about \"all servers\" or \"everything\", use `--all`\n5. **Use --server for specific** — when user mentions a server by name, use `--server `\n6. **Docker errors** — if docker is not installed or daemon not running, explain clearly\n7. **Network scan** — warn user it may take ~30 seconds\n8. **Security** — never expose raw JSON with hostnames/IPs in group chats, summarize instead\n9. **Deploy** — suggest `--local` for air-gapped environments\n\n## Security Notes\n\n- **SSH authentication**: Always prefer key-based auth over passwords. Never store plaintext passwords in config.\n- **Network scans**: Only run on your own local network. Warn user before scanning.\n- **Deploy**: Only deploy to servers you own. Confirm with user before remote installations.\n- **Config file permissions**: Keep config files readable only by owner (`chmod 600`).\n- **No telemetry**: homebutler sends zero data externally. All operations are local or to user-configured hosts only.\n\n## Error Handling\n\n- **SSH connection failed** → Check host/port/user in config, verify SSH key is registered on remote\n- **homebutler not found on remote** → Run `homebutler deploy --server ` first\n- **docker not installed** → Tell user docker is not available on that server\n- **docker daemon not running** → Suggest `sudo systemctl start docker`\n- **network scan timeout** → Normal on large subnets, suggest retrying\n- **permission denied** → May need sudo for ports/docker commands on some systems\n\n## Example Interactions\n\nUser: \"How's the server doing?\"\n→ Prefer `homebutler report`, summarize health, warnings, notable changes, and suggested actions. Use `homebutler status` only for a raw point-in-time status.\n\nUser: \"What changed / what owns this port / map my homelab\"\n→ Run `homebutler inventory scan` or `homebutler inventory export --format mermaid`.\n\nUser: \"Check all servers\"\n→ Run `homebutler status --all`, summarize each server's status\n\nUser: \"How's the Raspberry Pi?\"\n→ Run `homebutler status --server rpi`, summarize\n\nUser: \"What docker containers are running?\"\n→ Run `homebutler docker list`, list container names and states\n\nUser: \"Wake up the NAS\"\n→ Run `homebutler wake nas` (if configured) or ask for MAC address\n\nUser: \"Any alerts across all servers?\"\n→ Run `homebutler alerts --all`, report any warnings/critical\n\nUser: \"Deploy homebutler to the new server\"\n→ Run `homebutler deploy --server `, report result\n\nUser: \"Install uptime-kuma\"\n→ Run `homebutler install uptime-kuma`, report URL and status\n\nUser: \"What apps are available?\"\n→ Run `homebutler install list`, show available apps\n\nUser: \"Remove vaultwarden completely\"\n→ Run `homebutler install purge vaultwarden`, confirm deletion\n\nUser: \"Can I trust my backup?\"\n→ Run `homebutler backup drill ` or `homebutler backup drill --all`, report pass/fail and health status\n\nFile v2.3.0:_meta.json\n\n{\n \"ownerId\": \"kn79fa6trrr94j7388baz1wan581qrrg\",\n \"slug\": \"homebutler\",\n \"version\": \"2.3.0\",\n \"publishedAt\": 1777779718552\n}","readmeExcerpt":"Skill: Skills Owner: higangssh Summary: Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive. Tags: latest:2.4.0 Version history: v2.4.0 | 2026-09-26T01:25:35.512Z | user Pins moved to 0.39.0. v2.3.5 | 2026-09-16T14:46:41.508Z | user State when a read is appropriate, not only that it changes nothing; pin 0.35.2 v2.3","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"homebutler mcp"},{"language":"json","snippet":"{\"kind\": \"replaced\", \"target\": \"vaultwarden\",\n \"detail\": \"recreated, 4f2a1c → 9b7e03, vaultwarden:1.32 → vaultwarden:1.33\",\n \"text\": \"replaced: vaultwarden — recreated, …\"}"},{"language":"bash","snippet":"homebutler init\nhomebutler trust \nhomebutler watch install\nhomebutler watch tui\nhomebutler serve --token \nhomebutler serve install\nhomebutler deploy --server \nhomebutler upgrade"},{"language":"bash","snippet":"homebutler restore "},{"language":"bash","snippet":"homebutler trust \nhomebutler trust --reset"},{"language":"bash","snippet":"homebutler watch add \nhomebutler watch install\nhomebutler watch tui"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: homebutler\ndescription: Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive.\nmetadata:\n {\n \"openclaw\": {\n \"emoji\": \"🏠\",\n \"requires\": { \"anyBins\": [\"homebutler\"] },\n \"configPaths\": [\"homebutler.yaml\", \"~/.config/homebutler/config.yaml\"]\n }\n }\n---\n\n# Homebutler\n\n[homebutler](https://github.com/Higangssh/homebutler) remembers what a server\nlooked like last time and reports only the changes worth mentioning. One Go\nbinary: no database, and no agent on the machines it watches — the binary is\ndeployed there once and runs only when asked, over SSH.\n\n> This file is published to ClawHub as `@higangssh/homebutler`. The copy that\n> matters lives in the repository at `skills/SKILL.md`, and a test in `cmd/`\n> fails the build when a command or a tool named here stops existing.\n\n## Use the MCP server, not the shell\n\nStart `homebutler mcp` and call tools. Every tool is classed **read**, **write**\nor **destructive**, and that classification is what lets an agent decide what it\nmay do unattended. Shell commands are for the handful of things no tool exposes,\nand for anything the operator has to run themselves.\n\n```bash\nhomebutler mcp\n```\n\n### The tools\n\n**Read (27)** — nothing changes; see what a read still exposes, below.\n\n- `system_status`, `processes`, `open_ports`, `alerts`, `alerts_history`\n- `doctor` — health, exposure, backup age and readiness, as findings\n- `inventory_scan`, `inventory_export`, `network_scan`, `config_validate`\n- `docker_list`, `docker_logs`, `docker_stats`, `docker_top`, `docker_inspect`\n- `backup_list`, `install_list`, `install_status`\n- `watch_list`, `watch_history`\n- `proxmox_status`, `proxmox_guests`, `proxmox_node`, `proxmox_tasks`,\n `proxmox_task_status`, `proxmox_script_list`, `proxmox_script_command`\n\n**Write (13)** — something changes, or something leaves the machine.\n\n- `report` — the comparison, and it saves a snapshot\n- `docker_restart`, `wake`, `notify_test`\n- `backup_create`, `backup_drill`\n- `install_app`, `install_uninstall`\n- `watch_add`, `watch_check`, `watch_remove`\n- `proxmox_guest_start`, `proxmox_guest_reboot`\n\n**Destructive (4)** — ask first.\n\n- `backup_restore` — overwrites volumes with an archive\n- `docker_stop`, `install_purge` — stops a service, deletes its data\n- `proxmox_guest_shutdown`\n\n### What the classes mean for you\n\n- **read** — changes nothing on the machine, so running one needs no\n confirmation. What comes back is another matter: hostnames, internal\n addresses, what is listening, what is running, log contents. So read the\n machine the operator is asking about rather than every machine in the config;\n `--all` and `inventory_scan` are answers to a question somebody asked, not a\n way to begin. Summarise what matters instead of returning raw logs, port\n tables or JSON into a conversation other people can read.\n- **write** — something changes on the machine, or a m"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn79fa6trrr94j7388baz1wan581qrrg\",\n \"slug\": \"homebutler\",\n \"version\": \"2.4.0\",\n \"publishedAt\": 1790385935512\n}"},{"path":"skill-card.md","content":"## Description:\n\nHelps agents identify server changes and check system health, Docker, backups, and Proxmox through Homebutler.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[higangssh](https://clawhub.ai/user/higangssh)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nServer administrators and developers use this skill to review changes and health across configured servers, inspect Docker and backups, and request scoped maintenance or Proxmox actions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Server scans and diagnostic results may expose hostnames, internal addresses, ports, or log contents.\n\nMitigation: Limit reads to the requested hosts, seek approval for broad scans, and summarize sensitive results instead of sharing raw output.\n\nRisk: Write, restore, purge, service, and Proxmox power actions can change or delete operational data.\n\nMitigation: Require explicit operator approval for the specific target and action before execution; review configuration and backups first.\n\nRisk: Configured SSH access and tokens can grant control over monitored servers and Proxmox guests.\n\nMitigation: Review Homebutler configuration, tokens, and SSH access before installation and use.\n\n## Reference(s):\n\n- [Homebutler on ClawHub](https://clawhub.ai/higangssh/skills/homebutler)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Guidance, Shell commands, Configuration instructions]\n\n**Output Format:** [Markdown with optional structured tool results]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Summarized changes, findings, and suggested actions; command results can be requested as JSON.]\n\n## Skill Version(s):\n\n2.4.0 (source: ClawHub release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive. Skill: Skills Owner: higangssh Summary: Tells an agent what changed on a server since it last looked - plus status, Docker, backups, Proxmox. 44 MCP tools, each classed read, write or destructive. Tags: latest:2.4.0 Version history: v2.4.0 | 2026-09-26T01:25:35.512Z | user Pins moved to 0.39.0. v2.3.5 | 2026-09-16T14:46:41.508Z | user State when a read is appropriate, not only that it changes nothing; pin 0.35.2 v2.3","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1178,"uniquenessScore":52,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T16:44:59.176Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T16:44:59.176Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:51:05.968Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}