homebutler

# homebutler

> Single Go binary that remembers what a server looked like and reports only the changes worth mentioning — to a person (CLI, TUI, web dashboard) or an agent (MCP, typed JSON). Also Docker, backup/restore with drill, Proxmox, Wake-on-LAN, and multi-server over SSH.

## What it does
- `watch`: restart detection, crash analysis, flapping detection, incident history
- `watch tui`: terminal dashboard for all configured servers
- `serve`: embedded web dashboard with no separate frontend runtime
- Docker management: list, restart, stop, logs, stats
- App install: one-command self-hosted app deployment
- Backup/restore: Docker volume backup plus backup drill verification
- Notifications: Telegram, Slack, Discord, webhook
- Open ports, process list, network scan, Wake-on-LAN
- Multi-server SSH management and remote deploy
- Built-in MCP server for AI tools
- JSON output for scripts and agents

## Primary workflow
For monitoring, the main workflow is `watch`.

Use `watch` when you want to:
- detect service/container restarts
- capture pre-death and post-restart logs
- classify likely crash causes
- detect flapping loops
- inspect incident history later

`alerts` still exists, but it is the advanced threshold-based workflow for CPU, memory, and disk checks.

## Install
```bash
brew install Higangssh/homebutler/homebutler
# or
curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh
```

## Quick start
```bash
homebutler init
homebutler status --all
homebutler watch add nginx
homebutler watch start
homebutler watch history
homebutler notify test
homebutler serve
```

## Config
Primary config path:
- `~/.config/homebutler/config.yaml`

Resolution order:
1. `--config <path>`
2. `$HOMEBUTLER_CONFIG`
3. `~/.config/homebutler/config.yaml`
4. `./homebutler.yaml`

Main top-level config sections:
- `servers`
- `notify`
- `watch`
- `alerts`
- `wake`
- `backup_dir`

Legacy fallback config may still be read for compatibility, but `config.yaml` is the preferred source.

## AI / MCP
homebutler includes an MCP server for AI tools such as Claude, ChatGPT, Cursor, and other MCP-compatible clients.

Representative tools include:
- `system_status`
- `docker_list`
- `docker_restart`
- `docker_stop`
- `docker_logs`
- `wake`
- `open_ports`
- `network_scan`
- `alerts`

## Notes
- Prefer SSH key auth over password auth.
- Config files containing plaintext passwords should be owner-readable only.
- The web dashboard supports bearer token auth with `homebutler serve --token ...`.

## Links
- GitHub: https://github.com/Higangssh/homebutler
- MCP Server: https://glama.ai/mcp/servers/Higangssh/homebutler
- License: MIT