Quickstart

This page takes you from installing homebutler to a report that names what changed on your server. You need a Linux or macOS machine. Container features need the docker CLI on that machine.

Install homebutler
```
brew install Higangssh/homebutler/homebutler
```
For the install script, Go, a container, or a source build, see Installation.

Check the machine

homebutler status

🖥  homelab (linux/amd64)
   Uptime:  11h 31m
   CPU:     55.8% (4 cores)
   Memory:  7.5 / 7.8 GB (96.2%)
   Disk /: 1 / 19 GB (7%)

homebutler works without a config file. It uses built-in defaults until you run homebutler init.

Take a baseline
```
homebutler report
```
The first run has nothing to compare against, so it saves a snapshot under ~/.homebutler/reports/snapshots/ and says so:
```
📋 This is the butler's first look around — baseline created.
```

Read what changed

Run report again after something changes on the server, such as a container started, recreated, or removed:

homebutler report

🏠 Homebutler Report — homelab
   2026-10-24T19:43:05Z  ·  compared with 2026-10-24T19:42:56Z

── Needs Attention ───────────────────────────────────────────
   ⚠️  Port :8099/tcp is now reachable from every interface, answered by hb-demo (node:lts-alpine) — it was not before

── Notable Changes ───────────────────────────────────────────
   new  :8099/tcp  now hb-demo (node:lts-alpine)
   new  hb-demo    now running

Each change line has three columns: the kind of change, what it happened to, and what happened. Report lists the eight kinds.

The header names the snapshot the report compared against.

Run a health check

homebutler doctor

doctor checks disk and memory pressure, stopped containers, ports open on every interface, backups and notifications. Each finding ends with the command to run next:

⚠️ [backup] No backups found
   No .tar.gz backups found in /home/you/.homebutler/backups.
   → Create your first backup, then verify at least one important app with a drill.
   $ homebutler backup

Next steps

Connect your agent

Add homebutler to Claude, Cursor, or another MCP client.

Add your servers

Run homebutler init and reach other machines over SSH.

Back up and drill

Back up Docker volumes and prove the archive restores.

Watch for crashes

Capture the logs around a restart and detect restart loops.

Next steps​

Next steps