Skip to content
Back to search

homebutler

🏠 Tells you what changed on your server β€” only what's worth telling. Single Go binary, no database, nothing running on the machines it watches. MCP server built in.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Higangssh/homebutler with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Higangssh/homebutler'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/higangssh--homebutler/badge.svg)](/listings/higangssh--homebutler)

HTML

<a href="/listings/higangssh--homebutler"><img src="/api/listings/higangssh--homebutler/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

# One-line install (auto-detects OS/arch)
curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh

# Or via Homebrew
brew install Higangssh/homebutler/homebutler

# Or as a container β€” the hub that reaches your machines over SSH
docker run -d -p 8080:8080 -v ~/.config/homebutler:/config -v ~/.ssh:/root/.ssh:ro \
  ghcr.io/higangssh/homebutler serve --host 0.0.0.0 --token "$(openssl rand -hex 16)"

# Interactive setup β€” add your servers in seconds
homebutler init

Use it right away:

homebutler status                    # CPU, memory, disk, uptime
homebutler docker list               # running containers
homebutler inventory scan            # containers + ports + topology
homebutler report                    # butler-style health report + change summary
homebutler install uptime-kuma       # deploy a self-hosted app
homebutler backup drill uptime-kuma  # verify a backup actually restores
homebutler watch tui                 # terminal dashboard
homebutler serve                     # web dashboard at http://localhost:8080

Machine-readable output is available everywhere:

homebutler status --json
homebutler inventory scan --json
homebutler report --json

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 1,095 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/logo.png" alt="HomeButler logo" width="140">
  3. </p>
  4. <h1 align="center">HomeButler</h1>
  5. <p align="center">
  6. <strong>Only the changes worth mentioning.</strong><br>
  7. A single Go binary that remembers what your server looked like last time,
  8. and tells you β€” or an agent β€” what moved.
  9. </p>
  10. <p align="center">
  11. <a href="https://homebutler.dev">Website</a> Β·
  12. <a href="https://docs.homebutler.dev">Docs</a> Β·
  13. <a href="https://github.com/Higangssh/homebutler/releases">Releases</a>
  14. </p>
  15. <p align="center">
  16. <a href="https://go.dev"><img src="https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go&logoColor=white" alt="Go 1.25+"></a>
  17. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  18. <a href="https://github.com/Higangssh/homebutler/releases"><img src="https://img.shields.io/github/v/release/Higangssh/homebutler" alt="Release"></a>
  19. <a href="https://glama.ai/mcp/servers/Higangssh/homebutler"><img src="https://glama.ai/mcp/servers/Higangssh/homebutler/badges/score.svg" alt="homebutler MCP server"></a>
  20. <a href="https://coveralls.io/github/Higangssh/homebutler?branch=main"><img src="https://coveralls.io/repos/github/Higangssh/homebutler/badge.svg?branch=main" alt="Coverage Status"></a>
  21. <a href="https://pkg.go.dev/github.com/Higangssh/homebutler"><img src="https://pkg.go.dev/badge/github.com/Higangssh/homebutler.svg" alt="Go Reference"></a>
  22. </p>
  23. <p align="center">
  24. <img src="assets/mascot.png" alt="HomeButler mascot holding a tiny server" width="220">
  25. </p>
  26. <p align="center">
  27. <img src="assets/report-card.svg" alt="homebutler report output: a port answered by a different service flagged under Needs Attention, then what changed since the last report β€” a container gone, one new, one recreated behind the same name, a process running a different invocation, a port that changed owner β€” then current status and the command to verify the port" width="680">
  28. </p>
  29. That is the whole idea. Most homelab tools show you a graph of right now, and leave
  30. "does this matter?" to you. HomeButler remembers what your server looked like last
  31. time, decides what is worth saying, and says it β€” six containers before and six after
  32. is not "no change" when one of them is a different container.
  33. ## Reading a report
  34. ```bash
  35. homebutler report
  36. homebutler report --keep 7 # retain only the latest 7 snapshots
  37. homebutler report --no-save # preview without writing a snapshot
  38. ```
  39. `report` gives you a concise butler-style summary of your homelab: current health, warnings, notable changes since the previous snapshot, and suggested next commands. On the first run, HomeButler creates a baseline under `~/.homebutler/reports/snapshots/`; later runs compare against the latest snapshot. Old snapshots are pruned automatically (`--keep 30` by default) so reports do not grow forever.
  40. Section rules, labels, and severities are colour-coded in a terminal. Colour is
  41. dropped automatically when output is piped, redirected, or run from cron.
  42. ### Reading a change
  43. Every change line, like those in the card at the top, is three columns: **what kind of change**, **what it happened to**, and
  44. **what exactly happened**. The kind is one of eight words, and it is the same word in
  45. `--json`, so an agent branches on it without reading prose:
  46. | Kind | Means | You would see it after |
  47. | --- | --- | --- |
  48. | `gone` | it was there last time and is not now | `docker rm`, a service stopping, a port closing |
  49. | `new` | it was not there last time and is now | starting anything |
  50. | `replaced` | same name, different thing underneath | `docker compose up -d` β€” the container is recreated, so the name and the count are unchanged |
  51. | `image` | same container, different image | pulling a new tag |
  52. | `state` | same container, running where it was stopped, or the reverse; or a process that keeps restarting | a crash, a crash loop, or bringing something back up |
  53. | `port` | same port, a different process answering on it | one service taking over another's port |
  54. | `disk` | a mount moved by more than half a gigabyte | anything that writes |
  55. | `skipped` | the comparison could not be made | Docker was down when either snapshot was taken |
  56. `replaced` is the one the rest of this exists for. A container recreated under the
  57. same name leaves every count identical, which is why a report that compares counts β€”
  58. as this one did before 0.26.0 β€” answers "no significant changes" while the thing you
  59. were running has been swapped out underneath you.
  60. `skipped` is the second: homebutler says it could not compare rather than reporting
  61. nothing changed. An all-clear it cannot stand behind is worse than no answer.
  62. The header names the snapshot being compared against, so "what changed" is never
  63. ambiguous about the window it covers.
  64. πŸ“– **[What earns a line, and what is deliberately suppressed β†’](docs/report.md)**
  65. ## See it run
  66. <p align="center">
  67. <img src="assets/demo.gif" alt="a run through homebutler: report naming what moved since the last snapshot β€” a container gone, a port answered by something new, one recreated behind the same name β€” then the same answer as JSON with the kind as a field, then doctor listing what is exposed and what has never been backed up with the command for each, then a backup drill booting the archive in its own container and requiring an HTTP health check, then the same report on a phone, then the settings screen editing notification channels" width="820" />
  68. </p>
  69. <p align="center">
  70. <em>The whole thing in half a minute Β· <a href="https://www.youtube.com/watch?v=jwRuFoxNWOY">watch it full size</a></em>
  71. </p>
  72. ## Why homebutler?
  73. HomeButler helps you answer the boring but painful questions every homelab eventually creates:
  74. - What is running on my server right now?
  75. - Which container owns this port?
  76. - Why did this service restart at 3 AM?
  77. - Is my backup actually restorable?
  78. - Can I install this self-hosted app without hand-writing another compose file?
  79. - Can I let an AI assistant inspect my server without handing it a full SSH shell?
  80. No daemon required, no database. Run it from a terminal, cron, a web dashboard you start when you want one, or an AI agent.
  81. The design goal is simple: give humans and agents a narrow, structured interface to the server. HomeButler returns readable summaries and JSON instead of asking you to trust a black-box shell session.
  82. Self-hosting is not hard because one `docker compose up` is hard. It is hard because the maintenance never ends: ports collide, containers restart silently, backups look fine until restore day, and every server becomes a slightly different snowflake.
  83. HomeButler is a small operations toolkit for that messy middle.
  84. ### Alongside what you already run
  85. Keep Uptime Kuma for *is it up*, Beszel or Netdata for *the graph*, Dozzle for *the logs*.
  86. HomeButler answers the question none of them ask: **what is different from last time, and does it matter?**
  87. - **No agent on the machines it watches.** The binary is put there once with `homebutler deploy` and runs only when asked, over SSH β€” no daemon, no open port, nothing listening between runs.
  88. - **The judgement is a written rule, not a model.** What earns a line is in [docs/report.md](docs/report.md), and the same input gives the same report β€” no AI required, no account, no paid tier.
  89. - **It checks that a backup comes back.** A backup you have never restored is a folder. `backup drill` boots the archive as a second copy of the app, on a network and port of its own, and requires it to answer an HTTP health check before calling the archive good β€” then removes everything it made. A failed drill exits non-zero, so `backup drill --all` belongs in the same cron entry as `backup`. [docs/backup.md](docs/backup.md#drill-proving-the-backup-comes-back) has what it does and what it does not prove.
  90. ```
  91. πŸ” Integrity: βœ… tar valid (8 files)
  92. πŸš€ Boot: βœ… container started in 0s
  93. 🌐 Health: βœ… HTTP 200 on port 60405
  94. βœ… DRILL PASSED
  95. ```
  96. ## Quick Start
  97. ```bash
  98. # One-line install (auto-detects OS/arch)
  99. curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh
  100. # Or via Homebrew
  101. brew install Higangssh/homebutler/homebutler
  102. # Or as a container β€” the hub that reaches your machines over SSH
  103. docker run -d --name homebutler -p 8080:8080 -v ~/.config/homebutler:/config -v ~/.ssh:/root/.ssh:ro \
  104. -e HOMEBUTLER_TOKEN="$(openssl rand -hex 16)" ghcr.io/higangssh/homebutler
  105. docker exec homebutler printenv HOMEBUTLER_TOKEN # the token, to sign in to the dashboard
  106. # Interactive setup β€” add your servers in seconds
  107. homebutler init
  108. ```
  109. The install script and Homebrew cover macOS and Linux; on Windows, download the
  110. zip as described under [Windows](#windows). The container setup, its volumes and
  111. token are covered in [docs/docker.md](docs/docker.md).
  112. Use it right away:
  113. ```bash
  114. homebutler status # CPU, memory, disk, uptime
  115. homebutler docker list # running containers
  116. homebutler inventory scan # containers + ports + topology
  117. homebutler report # butler-style health report + change summary
  118. homebutler install uptime-kuma # deploy a self-hosted app
  119. homebutler backup drill uptime-kuma # verify a backup actually restores
  120. homebutler watch tui # terminal dashboard
  121. homebutler serve # web dashboard at http://localhost:8080
  122. ```
  123. Machine-readable output is available everywhere:
  124. ```bash
  125. homebutler status --json
  126. homebutler inventory scan --json
  127. homebutler report --json
  128. ```
  129. ## What else it does
  130. - **Install apps** β€” deploy Uptime Kuma, Jellyfin, Pi-hole, Gitea, Portainer, and more with one command
  131. - **Map your server** β€” see containers, exposed ports, system ports, and service topology
  132. - **Run a doctor check** β€” diagnose resource pressure, stopped containers, public ports, backup hygiene, notifications, report baseline readiness, and configured Proxmox endpoint reachability
  133. - **Catch crashes** β€” save logs before/after Docker, systemd, or PM2 restarts and detect flapping loops
  134. - **Verify backups** β€” boot backups in isolated containers before you trust them
  135. - **See a Proxmox cluster** β€” nodes, QEMU and LXC guests, storage, task status, and honest dashboard freshness, with power actions that name their target explicitly
  136. - **Use it anywhere** β€” CLI, JSON, web dashboard, or MCP for AI agents without giving them SSH
  137. ## 🩺 Doctor Check
  138. ```bash
  139. homebutler doctor
  140. homebutler doctor --strict # non-zero exit if warnings/failures are found
  141. homebutler doctor --json # automation / MCP friendly
  142. ```
  143. <p align="center">
  144. <img src="assets/doctor-card.svg" alt="homebutler doctor reporting a full disk, a stopped container, and a missing report baseline, each with the command to run next" width="700">
  145. </p>
  146. `doctor` is a read-only preflight for the problems homelab users usually discover too late: high disk or memory usage, stopped containers, public bind ports, stale or missing backups, missing notifications, whether `report` has a baseline for change detection, and whether each configured Proxmox endpoint is reachable with the token it has. Every finding names the next command to run, so `--strict` makes it usable from cron or CI β€” including a Proxmox host that is unreachable or rebooting.
  147. Every finding carries a `category`, and `--json` carries the same word, so a
  148. caller filters on it without reading the title:
  149. | Category | What it is about |
  150. | --- | --- |
  151. | `system` | CPU, memory, disk |
  152. | `docker` | containers that are stopped or unhealthy |
  153. | `exposure` | ports listening on every interface |
  154. | `backup` | backups missing, stale, never drilled, or growing without a retention limit |
  155. | `report` | whether there is a baseline to compare against |
  156. | `watch` | targets listed with nothing polling them |
  157. | `notifications` | channels configured, or never tested |
  158. | `proxmox` | an endpoint that cannot be reached with the token it has |
  159. | `config` | the config file itself β€” permissions, keys homebutler does not know |
  160. | `incomplete` | a collector did not answer, so this diagnosis is partial |
  161. | `overall` | nothing specific: the all-clear |
  162. `incomplete` is the one worth handling. It means the answer you are reading is
  163. missing a section, which is different from that section being fine.
  164. ### πŸ—‚ Config Validation
  165. ```bash
  166. homebutler config validate
  167. homebutler config validate --strict # exit non-zero on warnings too
  168. homebutler config validate --json
  169. ```
  170. `config validate` reads your config without starting anything and tells you
  171. which file was used, which of the four resolution rules picked it, and what
  172. homebutler actually made of each section. It exists because the two ways config
  173. goes wrong are both silent: a key homebutler does not recognise is dropped
  174. without a word, and a `--config` path that does not exist falls back to
  175. built-in defaults rather than failing.
  176. ```text
  177. Sections
  178. βœ“ servers 2 servers (homelab, nas)
  179. Β· notify not set
  180. βœ“ alerts cpu 95% Β· memory 85% Β· disk 90%
  181. Findings
  182. ⚠️ Line 5: field notifiy not found in the homebutler config
  183. β†’ Did you mean "notify"? Unrecognised keys are ignored silently.
  184. ```
  185. ## Watch and alerts
  186. ### πŸ”„ Process Restart Watch
  187. Your container crashed at 3 AM β€” but **why?** `homebutler watch` catches it the moment it happens, saves the dying logs, figures out the cause, and tells you if it's happening over and over.
  188. **Supported backends:** Docker (real-time event stream) Β· systemd (polling) Β· PM2 (polling)
  189. #### Step 1: Add targets to watch
  190. ```bash
  191. homebutler watch add nginx # Interactive: choose Docker / systemd / PM2
  192. homebutler watch add --kind docker nginx # or specify directly
  193. homebutler watch add --kind systemd nginx.service
  194. homebutler watch add --kind pm2 my-api
  195. homebutler watch add --kind systemd web --unit nginx.service # listed as web, checked as nginx.service
  196. homebutler watch list # See what you're watching
  197. ```
  198. #### Step 2: Start monitoring
  199. ```bash
  200. homebutler watch start # Foreground, Ctrl+C to stop
  201. homebutler watch start --interval 10s # Custom poll interval (default 30s)
  202. ```
  203. ```bash
  204. homebutler watch install # register it with systemd or launchd
  205. homebutler watch installed # is it registered?
  206. homebutler watch uninstall
  207. ```
  208. `watch install` hands the loop to whatever supervises the host β€” a systemd user
  209. unit on Linux, a launchd agent on macOS β€” so monitoring survives logout and
  210. reboot. Both are user-level and neither is a preference: on Linux the watch list
  211. lives in your home directory, so a root unit would find an empty list; on macOS
  212. Docker Desktop only runs inside a logged-in session, so a LaunchDaemon would
  213. poll a daemon that is not there. On Linux a user unit stops at logout unless
  214. lingering is on; `watch install` checks, and if it is off tells you to run
  215. `loginctl enable-linger $USER` (with sudo only if your system refuses it).
  216. `watch start` is the monitoring process. It watches the containers and services
  217. on the watch list for restarts, checks CPU, memory and disk against your
  218. thresholds, and runs any remediation rules you have configured β€” one process,
  219. one set of notification providers. `alerts --watch` still exists and does the
  220. threshold half on its own.
  221. Every endpoint under `proxmox:` in your config is polled too: unreachable or
  222. ACL-filtered endpoints and any guest listed under that endpoint's `guests:`
  223. report one incident when the problem starts and one recovery incident when it
  224. clears. A guest not listed there is observational only β€” `watch start` never
  225. alerts on it, deliberately stopped or not. See
  226. [Proxmox setup β†’](docs/proxmox.md#watch-integration) for the `guests:` field.
  227. When a crash is detected, you'll see:
  228. ```
  229. [03:14:22] INCIDENT: nginx (incident nginx-20260410-031422.581-7a2124)
  230. Crash: OOM β€” process killed by SIGKILL (oom, confidence: high)
  231. ⚠ FLAPPING: acute (3 restarts in short window)
  232. ```
  233. #### Step 3: Investigate
  234. ```bash
  235. homebutler watch history # List all incidents
  236. homebutler watch show <incident-id> # Full details
  237. ```
  238. `watch show` output includes:
  239. - **Pre-death logs** β€” what the process printed right before it died
  240. - **Post-restart logs** β€” what happened after the restart
  241. - **Crash analysis** β€” category (oom / panic / segfault / timeout / dependency / error), reason, confidence level, matched log patterns
  242. - **Flapping status** β€” if the process is stuck in a crash loop
  243. #### Crash Analysis
  244. Every incident is automatically analyzed using exit codes and log patterns:
  245. | Signal | Exit Code | Meaning |
  246. |--------|-----------|---------|
  247. | SIGKILL | 137 | OOM Killer or forced kill |
  248. | SIGSEGV | 139 | Segmentation fault (memory corruption) |
  249. | SIGTERM | 143 | Graceful shutdown request |
  250. | β€” | 1 | Application error |
  251. | β€” | 0 | Clean exit (may be intentional restart) |
  252. Log patterns like `panic:`, `Out of memory`, `Connection refused`, `FATAL`, and `timeout` are matched automatically to help identify the root cause.
  253. #### Flapping Detection
  254. Detects when a process is stuck in a restart loop (e.g., crash β†’ restart β†’ crash again):
  255. - **Acute** β€” 3+ restarts within 10 minutes (something is broken right now)
  256. - **Chronic** β€” 5+ restarts within 24 hours (slow recurring issue)
  257. Flapping incidents are tagged `[FLAPPING]` in history and highlighted in `watch show`.
  258. #### Notifications (optional, off by default)
  259. Notifications are disabled by default, which is useful for air-gapped or closed networks where everything runs locally.
  260. A minimal example in `~/.config/homebutler/config.yaml`:
  261. ```yaml
  262. notify:
  263. telegram:
  264. bot_token: "your-bot-token"
  265. chat_id: "your-chat-id"
  266. watch:
  267. enabled: true
  268. notify_on: flapping
  269. cooldown: 5m
  270. flapping:
  271. short_window: 10m
  272. short_threshold: 3
  273. long_window: 24h
  274. long_threshold: 5
  275. retention:
  276. max_incidents: 200
  277. alerts:
  278. cpu: 90
  279. memory: 85
  280. disk: 90
  281. rules:
  282. - name: cpu-spike
  283. metric: cpu
  284. threshold: 90
  285. action: notify
  286. - name: elsa-monitor-down
  287. metric: container
  288. kind: systemd # docker (default) | systemd | pm2
  289. watch: [lh-elsa-monitor.service]
  290. action: restart
  291. ```
  292. ### Restarting things that are not containers
  293. `action: restart` restarts Docker containers unless the rule says otherwise.
  294. `kind: systemd` or `kind: pm2` points it at a service or a PM2 app instead.
  295. The kind is written on the rule rather than looked up from the watch list, so
  296. restarting a host service is something you asked for in the config. It also
  297. means every rule written before `kind` existed keeps meaning exactly what it
  298. meant.
  299. Two things worth knowing before using it:
  300. **`systemctl restart` needs root or a polkit rule.** Running homebutler
  301. unprivileged, a systemd restart will be refused, reported as failed, and
  302. warned about when `alerts --watch` starts rather than when the rule first
  303. fires.
  304. **A target that is flapping is not restarted.** Restarting something already
  305. in a restart loop feeds the loop, and most systemd units carry
  306. `Restart=always`, so homebutler restarting them fights systemd's own backoff.
  307. The thresholds are the `watch.flapping` ones above, and the skip is reported
  308. rather than counted as either success or failure. This applies to Docker
  309. targets too.
  310. Legacy `~/.homebutler/watch/config.json` is still read as a fallback for watch-specific settings, and legacy `alerts.yaml` notify/webhook provider settings are still accepted for older setups.
  311. - `watch.enabled: true` β€” allow watch notifications
  312. - `watch.notify_on: flapping` β€” notify only when repeated restart loops are detected
  313. - `watch.notify_on: incident` β€” notify on every incident
  314. - `watch.notify_on: all` β€” notify on both incidents and flapping
  315. - `watch.notify_on: off` β€” disable watch notifications without removing provider config
  316. - `watch.cooldown: 5m` β€” suppress duplicate notifications for the same event fingerprint during the cooldown window
  317. - `watch.flapping` β€” optional advanced tuning for restart-loop detection
  318. - `watch.retention.max_incidents: 200` β€” how many incidents to keep on disk, newest first. The directory grows fastest exactly when a service is restarting in a loop. Set `-1` to keep everything.
  319. Each incident keeps up to 100 captured log lines per side, and at most 64 KB of them. Line counts alone do not bound a file: one stack trace or JSON document on a single line is arbitrarily long, and a container being OOM-killed is exactly the one likely to write one. A log that does not fit keeps its end β€” the last thing a process said is what explains why it stopped β€” and says how much was dropped.
  320. These settings can also be written under a `watch.notify:` block, which is the
  321. canonical form:
  322. ```yaml
  323. watch:
  324. notify:
  325. enabled: true
  326. notify_on: flapping
  327. cooldown: 5m
  328. flapping:
  329. short_window: 10m
  330. ```
  331. Both spellings are read, so either layout works. If a file contains both, the
  332. `notify:` block wins and `homebutler config validate` says so.
  333. #### Manage targets
  334. ```bash
  335. homebutler watch remove nginx # Stop watching
  336. homebutler watch check # One-shot check of Docker targets (no continuous monitoring)
  337. ```
  338. ### Alert Thresholds (Advanced)
  339. `alerts` still exists for CPU, memory, and disk threshold checks, but it is an advanced flow and not the recommended first step for new users.
  340. ```bash
  341. homebutler alerts --watch # default: 30s interval
  342. homebutler alerts --watch --interval 10s # check every 10 seconds
  343. homebutler alerts history # view alert history
  344. homebutler notify test # test your notification channels
  345. ```
  346. Default thresholds: CPU 90%, Memory 85%, Disk 90%. Start with `watch`, then add `alerts` only if you specifically want threshold-based checks.
  347. ## Backup & Restore
  348. One-command Docker backup β€” volumes, compose files, and env variables.
  349. ```bash
  350. homebutler backup # backup everything
  351. homebutler backup --service jellyfin # specific service
  352. homebutler backup --to /mnt/nas/backups/ # custom destination
  353. homebutler backup list # list backups
  354. homebutler restore ./backup.tar.gz # restore
  355. ```
  356. > ⚠️ Database services should be paused before backup for data consistency.
  357. πŸ“– **[Full backup documentation β†’](docs/backup.md)** β€” how it works, archive structure, security notes.
  358. ### πŸ” Backup Drill
  359. **"Having a backup" and "being able to restore" are different things.**
  360. Backup Drill boots your backup in an isolated Docker environment and verifies the app actually responds β€” like a fire drill for your data. A failed drill exits non-zero.
  361. ```bash
  362. homebutler backup drill uptime-kuma # verify one app
  363. homebutler backup drill --all # verify all apps
  364. homebutler backup drill --json # machine-readable output
  365. homebutler backup drill --archive ./file # use a specific backup
  366. ```
  367. Full walkthrough, including what a passing drill does *not* prove: [docs/backup.md](docs/backup.md#drill-proving-the-backup-comes-back).
  368. **What happens:**
  369. 1. Finds the latest backup archive
  370. 2. Verifies archive integrity (`tar` validation)
  371. 3. Creates an isolated Docker network + random port
  372. 4. Boots the app from backup data
  373. 5. Runs an HTTP health check
  374. 6. Reports pass/fail and cleans up everything
  375. ```
  376. πŸ” Backup Drill β€” uptime-kuma
  377. πŸ“¦ Backup: ~/.homebutler/backups/backup_2026-04-04_1711.tar.gz
  378. πŸ“ Size: 18.6 MB
  379. πŸ” Integrity: βœ… tar valid (8 files)
  380. πŸš€ Boot: βœ… container started in 0s
  381. 🌐 Health: βœ… HTTP 200 on port 58574
  382. ⏱️ Total: 2s
  383. βœ… DRILL PASSED
  384. ```
  385. **Zero risk** β€” runs in a completely isolated environment. Your running services are never touched.
  386. Supports health checks for: `nginx-proxy-manager`, `vaultwarden`, `uptime-kuma`, `pi-hole`, `gitea`, `jellyfin`, `plex`, `portainer`, `homepage`, `adguard-home`.
  387. ## App Install
  388. ```
  389. $ homebutler install list
  390. πŸ“¦ Available apps (15):
  391. uptime-kuma A self-hosted monitoring tool
  392. vaultwarden Lightweight Bitwarden-compatible password manager
  393. jellyfin Free software media system for streaming movies, TV, and music
  394. pi-hole Network-wide ad blocking via DNS filtering
  395. …
  396. ```
  397. > **`homebutler install uptime-kuma`** β€” Deploy self-hosted apps in seconds. Pre-checks Docker, ports, and duplicates. Generates `docker-compose.yml` automatically. [See all available apps β†’](#available-apps)
  398. Deploy self-hosted apps with a single command. Each app runs via **docker compose** with automatic pre-checks, health verification, and clean lifecycle management.
  399. ```bash
  400. # List available apps
  401. homebutler install list
  402. # Install (default port)
  403. homebutler install uptime-kuma
  404. # Install with custom port
  405. homebutler install uptime-kuma --port 8080
  406. # Install jellyfin with media directory
  407. homebutler install jellyfin --media /mnt/movies
  408. # Check status
  409. homebutler install status uptime-kuma
  410. # Stop (data preserved)
  411. homebutler install uninstall uptime-kuma
  412. # Stop + delete everything
  413. homebutler install purge uptime-kuma
  414. ```
  415. ### How it works
  416. ```
  417. ~/.homebutler/apps/
  418. └── uptime-kuma/
  419. β”œβ”€β”€ docker-compose.yml ← auto-generated, editable
  420. └── data/ ← persistent data (bind mount)
  421. ```
  422. - **Pre-checks** β€” Verifies docker is installed/running, port is available, no duplicate containers
  423. - **Compose-based** β€” Each app gets its own `docker-compose.yml` you can inspect and customize
  424. - **Data safety** β€” `uninstall` stops containers but keeps your data; `purge` removes everything, including the Docker volumes the app used, and names them
  425. - **Cross-platform** β€” Auto-detects docker socket (default, colima, podman)
  426. ### Available apps
  427. | App | Default Port | Description | Notes |
  428. |-----|-------------|-------------|-------|
  429. | `uptime-kuma` | 3001 | Self-hosted monitoring tool | |
  430. | `plex` | 32400 | Plex Media Server | `--media /path` to mount media dir |
  431. | `vaultwarden` | 8080 | Bitwarden-compatible password manager | |
  432. | `filebrowser` | 8081 | Web-based file manager | Its upstream project is archived and gets no further releases or security fixes |
  433. | `it-tools` | 8082 | Developer utilities (JSON, Base64, Hash, etc.) | |
  434. | `gitea` | 3002 | Lightweight self-hosted Git service | |
  435. | `jellyfin` | 8096 | Media system (movies, TV, music) | `--media /path` to mount media dir |
  436. | `homepage` | 3010 | Modern homelab dashboard | |
  437. | `stirling-pdf` | 8083 | All-in-one PDF tool (merge, split, convert, OCR) | |
  438. | `speedtest-tracker` | 8084 | Internet speed test with historical graphs | |
  439. | `mealie` | 9925 | Recipe manager and meal planner | |
  440. | `pi-hole` | 8088 | DNS ad blocking | ⚠️ Uses port 53 (DNS), NET_ADMIN capability |
  441. | `adguard-home` | 3000 | DNS ad blocker and privacy | ⚠️ Uses port 53 (DNS) |
  442. | `portainer` | 9443 | Docker management GUI | ⚠️ Mounts Docker socket (HTTPS) |
  443. | `nginx-proxy-manager` | 81 | Reverse proxy with SSL and web UI | ⚠️ Uses ports 80/443 |
  444. ### App-specific options
  445. ```bash
  446. # Jellyfin: mount your media library
  447. homebutler install jellyfin --media /mnt/movies
  448. # Pi-hole / AdGuard: DNS ad blocking (port 53 required)
  449. homebutler install pi-hole
  450. # ⚠️ If port 53 is in use (Linux): sudo systemctl disable --now systemd-resolved
  451. # Portainer: Docker GUI (mounts docker socket)
  452. homebutler install portainer
  453. # Access via HTTPS: https://localhost:9443
  454. # Nginx Proxy Manager: reverse proxy
  455. homebutler install nginx-proxy-manager
  456. # Default login: admin@example.com / changeme (change immediately!)
  457. # Any app: custom port
  458. homebutler install <app> --port 9999
  459. ```
  460. ### Safety checks
  461. - **Port conflict detection** β€” Checks if the port is already in use before install
  462. - **DNS mutual exclusion** β€” Warns if pi-hole and adguard-home are both installed
  463. - **Docker socket warning** β€” Alerts when an app requires Docker socket access (portainer)
  464. - **OS-specific guidance** β€” Linux gets systemd-resolved fix, macOS gets lsof command
  465. - **Post-install tips** β€” DNS setup, HTTPS access, default credential warnings
  466. > Want more apps? [Open an issue](https://github.com/Higangssh/homebutler/issues) or see [Contributing](CONTRIBUTING.md).
  467. ## Dashboards
  468. ### 🌐 Web Dashboard
  469. <p align="center">
  470. <img src="assets/web-dashboard.png" alt="homebutler web dashboard" width="900">
  471. </p>
  472. > **`homebutler serve`** β€” A web dashboard embedded in the single binary via `go:embed`. Servers, Docker containers, open ports, alerts and Wake-on-LAN from any browser. With `--token` it also edits the config: thresholds, notification channels, servers, Proxmox endpoints and wake devices.
  473. ### The Report tab, where you actually read it
  474. <p align="center">
  475. <img src="assets/report-tab.png" alt="the Report tab on a phone: what needs attention first β€” a container recreated and not running, a port answered by something new β€” then the changes with their kind word, including a container replaced behind the same name and a comparison that could not be made, then doctor's findings ordered by severity with the command to run for each" width="380">
  476. </p>
  477. The screen somebody opens after a notification. What needs attention first, then
  478. what moved with the kind word each change carries, then the snapshot being
  479. compared against and how old it is. A comparison that could not be made says so
  480. rather than reading as an all-clear.
  481. Loading it saves nothing β€” a page that took a snapshot every time it was opened
  482. would prune the baseline you wanted to compare against. Saving one is a button.
  483. <details>
  484. <summary>✨ Web Dashboard Highlights</summary>
  485. - **Server Overview** β€” See all servers at a glance with color-coded status (green = online, red = offline)
  486. - **System Metrics** β€” CPU, memory, disk usage with progress bars and color thresholds
  487. - **Docker Containers** β€” Running/stopped status with friendly labels ("Running Β· 4d", "Stopped Β· 6h ago")
  488. - **Top Processes** β€” Top processes sorted by CPU/memory with zombie detection
  489. - **Resource Warnings** β€” Visual CPU, memory, and disk thresholds in the dashboard
  490. - **Network Ports** β€” Open ports with process names and bind addresses
  491. - **Wake-on-LAN** β€” One-click wake buttons for configured devices
  492. - **Server Switching** β€” Dropdown to switch between local and remote servers
  493. - **Zero dependencies** β€” No Node.js runtime needed. Frontend is compiled into the Go binary at build time
  494. ```bash
  495. homebutler serve # Start on port 8080
  496. homebutler serve --port 3000 # Custom port
  497. homebutler serve --demo # Demo mode with realistic sample data
  498. homebutler serve install # Let the host keep it running
  499. ```
  500. </details>
  501. ### In Homepage
  502. Already run [Homepage](https://gethomepage.dev)? One `customapi` snippet in
  503. `services.yaml` puts a homebutler card on it: needs attention, changes since
  504. the last snapshot, containers running and stopped.
  505. [The snippet β†’](docs/web-dashboard.md#in-a-homepage-dashboard)
  506. ### πŸ–₯️ TUI Dashboard
  507. <p align="center">
  508. <img src="demo/demo-tui.gif" alt="homebutler TUI dashboard" width="800">
  509. </p>
  510. > **`homebutler watch tui`** β€” A terminal-based dashboard powered by Bubble Tea. Monitors all configured servers with real-time updates, color-coded resource bars, and Docker container status. No browser needed.
  511. ## πŸ—ΊοΈ Inventory & Topology
  512. ```bash
  513. homebutler inventory scan
  514. homebutler inventory show --filter exposed
  515. homebutler inventory export --format mermaid
  516. homebutler --json inventory scan
  517. ```
  518. `inventory scan` gives you a quick map of what is running on a server: system health, Docker containers, app ports, and system ports. Docker-published ports are connected back to the container that owns them, so local forwarding details like Colima/Lima stay understandable.
  519. ```text
  520. 🏠 Home Network
  521. Server homelab (192.168.1.10)
  522. Summary βœ… 1 running Β· βšͺ 1 stopped Β· 🌍 2 public ports Β· πŸ”’ 4 local ports
  523. πŸ“¦ Containers (2)
  524. β”œβ”€ βšͺ vaultwarden Β· not started
  525. β”‚ └─ image vaultwarden/server:latest
  526. └─ βœ… api-server Β· running
  527. β”œβ”€ image my-api:latest
  528. └─ exposes :8080 β†’ 8080/tcp
  529. 🌐 App Ports (1)
  530. └─ 🌍 :8080/tcp Β· api-server
  531. ```
  532. To answer "what is reachable from outside my machine/network?" without reading the whole tree, filter the scan to exposed ports only:
  533. ```bash
  534. homebutler inventory scan --filter exposed
  535. ```
  536. ```text
  537. 🏠 Home Network
  538. Server homelab
  539. 🌐 Exposed Ports
  540. β”œβ”€ :8080/tcp Β· api-server
  541. └─ :8443/tcp Β· dashboard
  542. ```
  543. Only ports listening on all interfaces (`0.0.0.0`, `::`, `*`) are shown. Anything bound to a specific address is hidden, including loopback and LAN addresses. Unsupported filter values return an error, as does combining `--filter` with `--json`; the default `inventory scan` output is unchanged.
  544. Use Mermaid export when you want a diagram for GitHub, Obsidian, docs, or an AI assistant:
  545. ```mermaid
  546. graph TD
  547. home["🏠 Home Network"] --> homelab["πŸ–₯ homelab<br/>192.168.1.10"]
  548. homelab --> c1["πŸ“¦ api-server<br/>running"]
  549. homelab --> p1["🌍 :8080/tcp<br/>api-server"]
  550. c1 -. exposes .-> p1
  551. ```
  552. ## 🧊 Proxmox VE
  553. ```bash
  554. homebutler proxmox status
  555. homebutler proxmox guests --status running
  556. homebutler proxmox guest shutdown --node pve1 --type lxc --vmid 105 --confirm
  557. homebutler proxmox task UPID:pve1:... --node pve1
  558. ```
  559. A Proxmox endpoint is its own kind of target, configured under `proxmox:` with an
  560. API token rather than SSH, so it does not join the `--server` or `--all` fan-out.
  561. TLS verification stays on: trust comes from a pinned SHA-256 fingerprint, then a
  562. CA file, and only then an explicit `insecure` fallback.
  563. Reads are plain. Power actions are not: every one of them takes an explicit
  564. endpoint, node, guest type and VMID, and refuses to run without `--confirm`,
  565. which is checked before any credential is read. They also need their own
  566. `action_token_id` (plus `action_token` or `action_token_file`) configured on
  567. the endpoint β€” the read token alone will not start, reboot, or shut down a
  568. guest; see [Proxmox setup β†’](docs/proxmox.md) for creating that second token.
  569. `shutdown` asks the guest to shut down cleanly β€” it is not Proxmox's hard
  570. `stop`, which cuts power and can leave a filesystem behind it. A successful
  571. action reports the task it submitted, not that the guest finished; `proxmox
  572. task` answers that separately.
  573. `proxmox script` prints the install command for a Community Script pinned to one
  574. commit, along with a warning that the script is not reviewed by homebutler and
  575. runs as root. It never fetches or runs it β€” see [#62](https://github.com/Higangssh/homebutler/issues/62)
  576. for why that line is where it is.
  577. πŸ“– **[Proxmox setup, tokens, and TLS β†’](docs/proxmox.md)**
  578. ## Installation
  579. ### Homebrew (Recommended)
  580. ```bash
  581. brew install Higangssh/homebutler/homebutler
  582. ```
  583. Automatically installs to PATH. Works on macOS and Linux.
  584. ### One-line Install
  585. ```bash
  586. curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh
  587. ```
  588. Auto-detects OS/architecture, downloads the latest release, and installs to PATH.
  589. macOS and Linux only; on Windows, use the zip below.
  590. ### Windows
  591. Download `homebutler_<version>_windows_amd64.zip` (or `_windows_arm64.zip`)
  592. from the [latest release](https://github.com/Higangssh/homebutler/releases/latest),
  593. extract `homebutler.exe`, and put it in a folder on your `PATH`.
  594. `homebutler upgrade` replaces it with the next release's. The npm package
  595. needs Windows 10 version 1803 or later, whose `tar.exe` it extracts the zip with.
  596. On Windows, `status` and what is built on it read this machine, and `ports` and
  597. `processes` say they are not supported. Servers in your config are reached
  598. over SSH as from any other machine, with keys read from
  599. `C:\Users\<you>\.ssh` ([configuration](docs/configuration.md)).
  600. ### npm (MCP server)
  601. ```bash
  602. npm install -g homebutler
  603. ```
  604. Downloads the Go binary automatically. This package publishes one command,
  605. `homebutler-mcp`, and it starts the MCP server β€” `npx -y homebutler@latest`
  606. launches that, not the CLI. For the command line, use one of the other
  607. installs above.
  608. ### Claude Desktop extension (MCP server)
  609. Download `homebutler_<version>_darwin_arm64.mcpb` (Apple silicon),
  610. `homebutler_<version>_darwin_amd64.mcpb` (Intel Mac),
  611. `homebutler_<version>_windows_amd64.mcpb` (Windows) or
  612. `homebutler_<version>_windows_arm64.mcpb` (Windows on Arm) from the
  613. [latest release](https://github.com/Higangssh/homebutler/releases/latest) and
  614. open it, or drag it onto Claude Desktop's Settings β†’ Extensions. The binary is
  615. inside, so nothing else needs installing. It starts read-only; see
  616. [the MCP docs](docs/mcp-server.md#claude-desktop-extension) to allow more.
  617. ### Go Install
  618. ```bash
  619. go install github.com/Higangssh/homebutler@latest
  620. ```
  621. ### Build from Source
  622. ```bash
  623. git clone https://github.com/Higangssh/homebutler.git
  624. cd homebutler
  625. make build-all
  626. ```
  627. `make build-all` compiles the web dashboard into the binary and needs Node
  628. installed. `make build` skips it β€” the CLI is complete either way, and
  629. `homebutler serve` then says the dashboard is missing and names the two ways
  630. to get it.
  631. ### Uninstall
  632. ```bash
  633. rm $(which homebutler) # Remove binary
  634. rm -rf ~/.config/homebutler # Remove config (optional)
  635. ```
  636. ## Usage
  637. ```
  638. homebutler <command> [flags]
  639. Commands:
  640. status System status (CPU, memory, disk, uptime)
  641. doctor Diagnose health, exposure, backups, and readiness
  642. config validate Check the config file and report what is ignored
  643. docker list List running containers
  644. install <app> Install a self-hosted app (docker compose)
  645. alerts Show current alert status
  646. watch tui TUI dashboard (monitors all configured servers)
  647. watch add/list/remove Manage watched containers, systemd units, PM2 apps
  648. watch check/start One-shot or continuous restart detection
  649. watch history/show Browse restart history
  650. proxmox status Proxmox VE cluster, nodes, guests, and storage
  651. serve Web dashboard (browser-based, go:embed)
  652. Flags:
  653. --json JSON output (default: human-readable)
  654. --verbose, -v Show detailed error information
  655. --server <name> Run on a specific remote server
  656. --all Run on all configured servers in parallel
  657. --port <number> Port for serve command (default: 8080)
  658. --config <path> Config file (auto-detected, see Configuration)
  659. ```
  660. Run `homebutler --help` for all commands.
  661. <details>
  662. <summary>πŸ“‹ All Commands & Flags</summary>
  663. ```
  664. Commands:
  665. init Interactive setup wizard
  666. config validate Check the config file and report what is ignored
  667. status System status (CPU, memory, disk, uptime)
  668. doctor Diagnose health, exposure, backups, and readiness
  669. watch tui TUI dashboard (monitors all configured servers)
  670. watch add <name> Watch a container, unit, or PM2 app (--kind, --unit)
  671. watch list Show watched targets
  672. watch remove <name> Remove a target from the watch list
  673. watch check One-shot restart check (Docker targets only)
  674. watch start Continuous monitoring: restarts, thresholds, rules
  675. watch install Register watch with systemd or launchd
  676. watch installed Report whether it is registered
  677. watch uninstall Remove the service unit
  678. watch history List restart history (alias: incidents)
  679. watch show <id> Show restart details with logs
  680. serve Web dashboard (browser-based, go:embed)
  681. docker list List running containers
  682. docker restart <n> Restart a container
  683. docker stop <n> Stop a container
  684. docker logs <n> Show container logs
  685. docker top <n> Show processes running inside a container
  686. docker inspect <n> Show image, state, ports, mounts, networks, health
  687. report What changed since the last snapshot
  688. inventory scan Map containers, ports, and topology
  689. inventory show Same as scan (--filter exposed narrows it)
  690. inventory export Export the map (--format mermaid)
  691. proxmox status Proxmox VE cluster, nodes, guests, storage
  692. proxmox guests List QEMU and LXC guests
  693. proxmox node <n> Node detail
  694. proxmox guest ... start / shutdown / reboot (needs --confirm)
  695. proxmox task <upid> Task status for an action already submitted
  696. proxmox tasks Recent tasks on a node
  697. proxmox script Community Script install commands (prints, never runs)
  698. notify test Send a test notification through configured providers
  699. wake <name> Send Wake-on-LAN packet
  700. ports List open ports with process info
  701. ps Show top processes (alias: processes)
  702. ps --sort mem Sort by memory instead of CPU
  703. ps --limit 20 Show top 20 (default: 10, 0 = all)
  704. network scan Discover devices on LAN
  705. alerts Show current alert status
  706. alerts --watch Thresholds only (watch start covers these too)
  707. trust <server> Register SSH host key (TOFU)
  708. trust <s> --reset Replace a changed host key once you accept the new one
  709. backup Backup Docker volumes, compose files, and env
  710. backup list List existing backups
  711. backup drill <app> Verify backup restores correctly (isolated)
  712. backup drill --all Verify all apps in backup
  713. restore <archive> Restore from a backup archive
  714. upgrade Upgrade local + all remote servers to latest
  715. deploy Install homebutler on remote servers
  716. install <app> Install a self-hosted app (docker compose)
  717. install list List available apps
  718. install status <a> Check installed app status
  719. install uninstall Stop app (keep data)
  720. install purge Stop app + delete all data
  721. mcp Start MCP server (JSON-RPC over stdio)
  722. version Print version
  723. Flags:
  724. --json JSON output (default: human-readable)
  725. --verbose, -v Show detailed error information
  726. --server <name> Run on a specific remote server
  727. --all Run on all configured servers in parallel
  728. --port <number> Port for serve command (default: 8080)
  729. --demo Run serve with realistic demo data
  730. --watch Continuous monitoring mode (alerts command)
  731. --interval <dur> Watch interval, e.g. 30s, 1m (default: 30s)
  732. --config <path> Config file (auto-detected, see Configuration)
  733. --local Upgrade only the local binary (skip remote servers)
  734. --local <path> Use local binary for deploy (air-gapped)
  735. --service <name> Target a specific Docker service (backup/restore)
  736. --allow-bind <path> Host path a restore may write a bind mount to (repeatable)
  737. --endpoint <name> Proxmox endpoint from config (optional if only one)
  738. --confirm Required for a Proxmox guest power action
  739. --to <path> Custom backup destination directory
  740. --archive <path> Specific backup archive for drill
  741. --all Verify all supported apps (backup drill)
  742. ```
  743. </details>
  744. <details>
  745. <summary>🌐 Web Dashboard</summary>
  746. `homebutler serve` starts an embedded web dashboard β€” no Node.js, no Docker, no extra dependencies.
  747. ```bash
  748. homebutler serve # http://localhost:8080
  749. homebutler serve --port 3000 # custom port
  750. homebutler serve --demo # demo mode with sample data
  751. homebutler serve install # hand it to launchd or systemd, so it survives logout
  752. homebutler serve uninstall # and take it back
  753. ```
  754. The installed unit records the address and never the token β€” that comes from
  755. `web.token` in the config file, because `--token` is visible in `ps` to every
  756. user on the machine. In a container, set `HOMEBUTLER_TOKEN` instead; it is used
  757. when neither of the others is set, and never written to the config.
  758. πŸ“– **[Web dashboard details β†’](docs/web-dashboard.md)**
  759. </details>
  760. ## Configuration
  761. ```bash
  762. homebutler init # interactive setup wizard
  763. ```
  764. πŸ“– **[What `report` compares β†’](docs/report.md)** β€” what earns a line, what is deliberately suppressed, and why.
  765. πŸ“– **[Configuration details β†’](docs/configuration.md)** β€” config file locations, watch/notify options, and advanced alert thresholds.
  766. ## Multi-server
  767. Manage multiple servers from a single machine over SSH.
  768. ```bash
  769. homebutler status --server rpi # query specific server
  770. homebutler status --all # query all in parallel
  771. homebutler deploy --server rpi # install on remote server
  772. homebutler upgrade # upgrade all servers
  773. ```
  774. πŸ“– **[Multi-server setup β†’](docs/multi-server.md)** β€” SSH auth, config examples, deploy & upgrade.
  775. ## MCP Server
  776. Built-in [MCP](https://modelcontextprotocol.io/) server β€” an agent gets the same report as typed JSON, kind, target and detail rather than a sentence to parse, and every tool is classed read, write or destructive.
  777. > **Use natural language when you want automation.** MCP clients can call homebutler tools to check server status, list Docker containers, inspect ports, or run operational workflows.
  778. ```json
  779. {
  780. "mcpServers": {
  781. "homebutler": {
  782. "command": "npx",
  783. "args": ["-y", "homebutler@latest"]
  784. }
  785. }
  786. }
  787. ```
  788. Works with Claude Desktop, ChatGPT, Cursor, Windsurf, and any MCP client.
  789. To let an agent look without being able to change anything, add `"--max-risk", "read"` to `args`. Tools that change something are not offered and are refused if called by name, and `report` runs without saving a snapshot. Read mode stops changes, not reading: logs, container details and everything else a read returns are still visible. [What read mode covers β†’](docs/mcp-server.md#read-only-mode)
  790. πŸ“– **[MCP server setup β†’](docs/mcp-server.md)** β€” supported clients, available tools, agent skills. The same guide is at [docs.homebutler.dev/agents/mcp-server](https://docs.homebutler.dev/agents/mcp-server).
  791. ## Architecture
  792. > **The butler watches, decides what is worth saying, and says it β€” to you or to an agent.**
  793. >
  794. > Something changes β†’ `report` names it and ranks it β†’ a notification, the dashboard, or an MCP call
  795. > carries the same answer.
  796. ```
  797. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  798. β”‚ CLI β”‚ β”‚ MCP β”‚ β”‚ Web β”‚
  799. β”‚ stdout β”‚ β”‚ stdio β”‚ β”‚ :8080 β”‚
  800. β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜
  801. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  802. β–Ό
  803. internal/*
  804. system Β· docker Β· ports Β· network
  805. wake Β· alerts Β· remote (SSH)
  806. ```
  807. **Three interfaces, one core:**
  808. | Interface | Transport | Use case |
  809. |-----------|-----------|----------|
  810. | **CLI** | Shell stdout/stderr | Terminal, scripts, AI agents via `exec` |
  811. | **MCP** | JSON-RPC over stdio | Claude Desktop, ChatGPT, Cursor, any MCP client |
  812. | **Web** | HTTP (`go:embed`) | Browser dashboard, on-demand with `homebutler serve` |
  813. All three call the same `internal/` packages β€” no code duplication.
  814. An agent reads the same report a person does, and gets the parts it has to branch on
  815. rather than a screen it has to interpret:
  816. ```python
  817. report = json.loads(subprocess.run(
  818. ["homebutler", "report", "--json"], capture_output=True, text=True).stdout)
  819. for change in report["notable_changes"]:
  820. if change["kind"] == "replaced": # the container came back as something else
  821. redeploy(change["target"])
  822. else:
  823. log(change["text"]) # "port: :8080/tcp β€” nginx β†’ caddy"
  824. ```
  825. Every line carries `text` as well, so a caller that only wants to print it does not have
  826. to put the sentence back together. A run that found nothing returns `"notable_changes": []`,
  827. so the loop above does nothing on a quiet day.
  828. Nothing above this is homebutler's business: an MCP client, a chat bot, a cron line or a
  829. person at a terminal all reach the same answer.
  830. **No ports opened by default.** CLI and MCP use stdin/stdout only. The web dashboard is opt-in (`homebutler serve`, binds `127.0.0.1`).
  831. ## Contributing
  832. Contributions welcome! Please open an issue first to discuss what you'd like to change.
  833. [CONTRIBUTING.md](CONTRIBUTING.md) covers what homebutler accepts and what a new
  834. target has to prove.
  835. ## Security
  836. Found a vulnerability? Report it privately through
  837. [the Security tab](https://github.com/Higangssh/homebutler/security/advisories/new)
  838. rather than a public issue. [SECURITY.md](SECURITY.md) covers what is in scope
  839. and what to expect.
  840. ## License
  841. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.