homebutler

HomeButler

伝える価値のある変更だけをお知らせします。
サーバーの前回の状態を記憶する単一の Go バイナリです。 何が変わったのかを、あなたやエージェントに伝えます。

ウェブサイト · ドキュメント · リリース

アイデアはこれだけです。ほとんどのホームラボツールは現在の状態をグラフで表示し、「これは重要なのか？」という判断をあなたに委ねます。HomeButlerはサーバーの前回の状態を記憶し、伝える価値のあることを判断して知らせます。コンテナの数が前後で6個ずつでも、そのうち1つが別のコンテナに置き換わっているなら、「変更なし」ではありません。

レポートの見方

homebutler report
homebutler report --keep 7      # retain only the latest 7 snapshots
homebutler report --no-save     # preview without writing a snapshot

report は、ホームラボの現在の健全性、警告、前回のスナップショットからの注目すべき変更、次に実行するコマンドの提案を、執事のように簡潔にまとめて表示します。初回の実行時に、HomeButlerは ~/.homebutler/reports/snapshots/ にベースラインを作成します。以降の実行では、最新のスナップショットと比較します。レポートが際限なく増えないよう、古いスナップショットは自動的に削除されます（デフォルトの --keep 30）。

セクションのルール、ラベル、重大度は、ターミナル上で色分けされます。出力がパイプやリダイレクトに渡された場合、または cron から実行された場合は、色が自動的に除去されます。

変更を読む

冒頭のカードにあるような各変更行は、変更の種類、変更の対象、具体的に起きたことの3列で構成されています。種類は8つの単語のいずれかで、--jsonでも同じ単語が使われるため、エージェントは説明文を読まずに種類に応じて分岐できます。

この仕組みのほかの部分が存在する理由となるのが、replacedです。同じ名前でコンテナーが再作成されると、すべての数が変わりません。そのため、0.26.0以前のように数を比較するレポートでは、実行中のものが裏で入れ替わっているにもかかわらず、「重要な変更はありません」と回答してしまいます。

2つ目はskippedです。homebutlerは、何も変わっていないと報告するのではなく、比較できなかったことを伝えます。確証のない問題なしの報告は、回答しないことよりも悪いからです。

ヘッダーには比較対象のスナップショット名が記載されるため、「何が変わったか」がどの期間を対象にしているのか曖昧になりません。

📖 どのような変更が記録され、何が意図的に除外されるのか →

動作を見る

すべての動作を30秒でご紹介 · フルサイズで見る

なぜhomebutlerなのか？

HomeButlerは、ホームラボを運用しているといずれ直面する、ありふれているのに厄介な疑問への答えを見つけるのに役立ちます。

• 今、サーバーでは何が動いていますか？
• このポートを使っているコンテナーはどれですか？
• このサービスが午前3時に再起動したのはなぜですか？
• このバックアップは本当に復元できますか？
• composeファイルをまた手書きせずに、このセルフホストアプリをインストールできますか？
• SSHシェルへの完全なアクセスを渡さずに、AIアシスタントにサーバーを調べさせることはできますか？

デーモンもデータベースも不要です。ターミナル、cron、必要なときに起動するWebダッシュボード、またはAIエージェントから実行できます。

設計目標はシンプルです。人間とエージェントがサーバーを操作するための、限定的で構造化されたインターフェースを提供します。HomeButlerは読みやすい要約とJSONを返すため、ブラックボックスのシェルセッションを信用する必要はありません。

セルフホストが難しいのは、docker compose upが難しいからではありません。メンテナンスが終わらないからです。ポートは競合し、コンテナーは気付かないうちに再起動し、バックアップは復元する日まで問題なく見え、サーバーごとに少しずつ異なる環境になっていきます。

HomeButlerは、そんな雑然とした運用の中間領域を支える、小さな運用ツールキットです。

現在使っているツールと併用

「稼働しているか」の確認には Uptime Kuma、「グラフ」には Beszel または Netdata、「ログ」には Dozzle を引き続き使いましょう。 HomeButler は、それらのツールが尋ねない質問に答えます。前回と何が違うのか、そしてそれは重要なのか？

• 監視対象のマシンにエージェントを置きません。 バイナリを homebutler deploy で一度配置し、SSH 経由で要求されたときだけ実行します。デーモンも、開いたポートも、実行の合間に待ち受けるものもありません。

• 判断基準はモデルではなく、記述されたルールです。 何を報告するかは docs/report.md に記載されており、同じ入力には同じレポートが返されます。AI もアカウントも有料プランも必要ありません。

• バックアップから復元できるかを確認します。 一度も復元したことのないバックアップは、ただのフォルダーです。backup drill はアーカイブをアプリの複製として独自のネットワークとポートで起動し、アーカイブを正常と判定する前に HTTP ヘルスチェックへの応答を必須とします。その後、作成したものをすべて削除します。ドリルに失敗するとゼロ以外の終了コードで終了するため、backup drill --all は backup と同じ cron エントリーに含めてください。docs/backup.md では、実行内容と、証明できない内容を説明しています。

  🔐 Integrity: ✅ tar valid (8 files)
  🚀 Boot: ✅ container started in 0s
  🌐 Health: ✅ HTTP 200 on port 60405
  
  ✅ DRILL PASSED
  

クイックスタート

# 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

コンテナーとして実行し、SSH 経由でマシンに接続する方法については、docs/docker.md を参照してください。 docker run -v ~/.config/homebutler:/config -v ~/.ssh:/root/.ssh:ro ghcr.io/higangssh/homebutler

すぐに使い始められます。

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

機械可読形式の出力は、どこでも利用できます。

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

そのほかの機能

• アプリをインストール — Uptime Kuma、Jellyfin、Pi-hole、Gitea、Portainer などを、1 つのコマンドでデプロイします
• サーバーをマッピング — コンテナー、公開ポート、システムポート、サービスのトポロジーを確認します
• 診断チェックを実行 — リソースの逼迫、停止したコンテナー、公開ポート、バックアップの健全性、通知、レポートのベースライン準備状況、設定済みの Proxmox エンドポイントへの到達性を診断します
• クラッシュを検知 — Docker、systemd、PM2 の再起動前後のログを保存し、再起動を繰り返すループを検知します
• バックアップを検証 — 信頼する前に、隔離されたコンテナーでバックアップを起動します
• Proxmox クラスターを確認 — ノード、QEMU および LXC ゲスト、ストレージ、タスクの状態、ダッシュボードの鮮度を正直に表示し、対象を明示する電源操作を実行します
• どこでも利用 — CLI、JSON、ウェブダッシュボード、または SSH を渡さずに AI エージェントが使える MCP

🩺 Doctor Check

homebutler doctor
homebutler doctor --strict          # non-zero exit if warnings/failures are found
homebutler doctor --json            # automation / MCP friendly

doctor は、ホームラボのユーザーが手遅れになってから気づきがちな問題を事前に確認する読み取り専用の機能です。ディスクやメモリの使用率の高さ、停止中のコンテナ、外部公開されているバインドポート、古いバックアップや存在しないバックアップ、通知の未設定、変更検出用のベースラインが report にあるかどうか、さらに設定済みの各 Proxmox エンドポイントに、そのトークンで接続できるかをチェックします。各検出結果には次に実行するコマンドが示されるため、--strict を使えば cron や CI からも実行できます。接続できない、または再起動中の Proxmox ホストも対象です。

各検出結果には category が含まれ、--json にも同じ値が含まれます。そのため、呼び出し元はタイトルを読まずにカテゴリで絞り込めます。

特に対応が必要なのは incomplete です。これは、表示されている結果にセクションが欠けていることを意味し、そのセクションに問題がないこととは異なります。

🗂 Config Validation

homebutler config validate
homebutler config validate --strict   # exit non-zero on warnings too
homebutler config validate --json

config validate は、何も起動せずに設定を読み込み、使用されたファイル、4 つの解決ルールのうちどれが選ばれたか、そして homebutler が各セクションをどのように解釈したかを通知します。この機能があるのは、設定で起きる 2 種類の問題がどちらも表面化しないためです。homebutler が認識しないキーは何も通知せずに無視され、存在しない --config のパスを指定すると、エラーにならず組み込みのデフォルト設定にフォールバックします。

Sections
   ✓ servers     2 servers (homelab, nas)
   · notify      not set
   ✓ alerts      cpu 95% · memory 85% · disk 90%

Findings
   ⚠️ Line 5: field notifiy not found in the homebutler config
      → Did you mean "notify"? Unrecognised keys are ignored silently.

監視とアラート

🔄 プロセス再起動の監視

コンテナが午前 3 時にクラッシュしました。原因は何でしょうか？ homebutler watch は発生した瞬間に検知して、終了時のログを保存し、原因を特定して、何度も繰り返し発生しているかどうかを知らせます。

対応バックエンド： Docker（リアルタイムイベントストリーム） · systemd（ポーリング） · PM2（ポーリング）

ステップ 1：監視するターゲットを追加する

homebutler watch add nginx              # Interactive: choose Docker / systemd / PM2
homebutler watch add --kind docker nginx          # or specify directly
homebutler watch add --kind systemd nginx.service
homebutler watch add --kind pm2 my-api
homebutler watch list                   # See what you're watching

ステップ 2：監視を開始する

homebutler watch start                  # Foreground, Ctrl+C to stop
homebutler watch start --interval 10s   # Custom poll interval (default 30s)

homebutler watch install     # register it with systemd or launchd
homebutler watch installed   # is it registered?
homebutler watch uninstall

watch install を実行すると、監視処理はホストの監視機構に引き継がれます。Linux では systemd のユーザーユニット、macOS では launchd エージェントが使われるため、ログアウトや再起動後も監視が継続します。どちらもユーザーレベルで動作し、任意に選べるものではありません。Linux では監視対象リストがホームディレクトリに保存されるため、root のユニットでは空のリストが読み込まれます。macOS では Docker Desktop はログイン中のセッション内でのみ動作するため、LaunchDaemon は存在しないデーモンをポーリングすることになります。Linux では lingering が有効でないと、ログアウト時にユーザーユニットが停止します。watch install は状態を確認し、無効な場合は loginctl enable-linger $USER の実行を案内します（システムによって拒否された場合に限り、sudo を使用してください）。

watch start は監視プロセスです。監視対象リストにあるコンテナとサービスを監視して再起動を検出し、CPU、メモリ、ディスク使用量をしきい値と照合し、設定済みの修復ルールを実行します。通知プロバイダーのセットは、すべてこの 1 つのプロセスで使用されます。alerts --watch も引き続き利用でき、しきい値の確認を単独で行います。

設定内の proxmox: にあるすべてのエンドポイントもポーリングされます。到達不能または ACL によってフィルタリングされたエンドポイント、およびそのエンドポイントの guests: に記載されているゲストについて、問題の発生時に 1 件、解消時に復旧インシデントが 1 件報告されます。そこに記載されていないゲストは、意図的に停止されているかどうかにかかわらず、観測のみの対象です。guests: フィールドについては、Proxmox のセットアップ →を参照してください。

クラッシュが検出されると、次のように表示されます。

[03:14:22] INCIDENT: nginx (incident nginx-20260410-031422.581-7a2124)
  Crash: OOM — process killed by SIGKILL (oom, confidence: high)
  ⚠ FLAPPING: acute (3 restarts in short window)

ステップ 3：調査する

homebutler watch history                # List all incidents
homebutler watch show <incident-id>     # Full details

watch show の出力には、次の情報が含まれます。

• 終了前のログ — プロセスが終了する直前に出力した内容
• 再起動後のログ — 再起動後に発生した内容
• クラッシュ分析 — カテゴリ（oom / panic / segfault / timeout / dependency / error）、原因、信頼度、該当するログパターン
• フラッピングの状態 — プロセスがクラッシュループに陥っている場合

クラッシュ分析

各インシデントは、終了コードとログパターンを使って自動的に分析されます。

panic:、Out of memory、Connection refused、FATAL、timeout などのログパターンが自動的に照合され、根本原因の特定に役立ちます。

フラッピングの検出

プロセスが再起動ループ（例：クラッシュ → 再起動 → 再びクラッシュ）に陥っていることを検出します。

• 急性 — 10 分以内に 3 回以上の再起動（現在、何らかの問題が発生しています）
• 慢性 — 24 時間以内に 5 回以上の再起動（再発を繰り返す緩やかな問題）

フラッピングインシデントには履歴内で [FLAPPING] のタグが付き、watch show で強調表示されます。

通知（任意、デフォルトでは無効）

通知はデフォルトで無効になっています。すべてがローカルで動作するエアギャップ環境や閉鎖ネットワークでは、この設定が便利です。

~/.config/homebutler/config.yaml に記述する最小限の例：

notify:
  telegram:
    bot_token: "your-bot-token"
    chat_id: "your-chat-id"

watch:
  enabled: true
  notify_on: flapping
  cooldown: 5m
  flapping:
    short_window: 10m
    short_threshold: 3
    long_window: 24h
    long_threshold: 5
  retention:
    max_incidents: 200

alerts:
  cpu: 90
  memory: 85
  disk: 90
  rules:
    - name: cpu-spike
      metric: cpu
      threshold: 90
      action: notify

    - name: elsa-monitor-down
      metric: container
      kind: systemd          # docker (default) | systemd | pm2
      watch: [lh-elsa-monitor.service]
      action: restart

コンテナ以外の再起動

action: restart は、ルールで別途指定されていない限り、Docker コンテナを再起動します。 kind: systemd または kind: pm2 を指定すると、サービスまたは PM2 アプリを再起動します。

kind は監視リストから参照するのではなくルールに記述するため、ホストサービスの再起動は設定で明示的に指定した場合にのみ行われます。また、kind が導入される前に作成されたルールは、これまでとまったく同じ動作をします。

利用する前に、知っておきたいことが 2 つあります。

systemctl restart には root 権限または polkit ルールが必要です。 homebutler を非特権ユーザーで実行している場合、systemd の再起動は拒否され、失敗として報告されます。また、ルールが最初に発火したときではなく、alerts --watch の起動時に警告されます。

フラッピングしているターゲットは再起動されません。 すでに再起動ループに入っているものを再起動するとループを加速させます。また、ほとんどの systemd ユニットには Restart=always が設定されているため、homebutler による再起動は systemd 自身のバックオフ処理と競合します。しきい値には上記の watch.flapping を使用します。スキップは成功にも失敗にも数えられず、その旨が報告されます。この動作は Docker のターゲットにも適用されます。

従来の ~/.homebutler/watch/config.json は、引き続き監視固有の設定のフォールバックとして読み込まれます。また、従来の alerts.yaml に記述された通知／Webhook プロバイダー設定も、以前のセットアップ向けに引き続き受け付けられます。

• watch.enabled: true — 監視通知を有効にします

• watch.notify_on: flapping — 繰り返し発生する再起動ループを検出した場合にのみ通知します

• watch.notify_on: incident — インシデントごとに通知します

• watch.notify_on: all — インシデントとフラッピングの両方を通知します

• watch.notify_on: off — プロバイダー設定を削除せずに、監視通知を無効にします

• watch.cooldown: 5m — クールダウン期間中、同じイベントフィンガープリントに対する重複通知を抑制します

• watch.flapping — 再起動ループ検出を調整するための任意の詳細設定です

• watch.retention.max_incidents: 200 — ディスクに保存するインシデント数です。新しいものから順に保持します。サービスが再起動ループに入っているときに、ディレクトリの増加が最も速くなります。すべて保持するには -1 を設定します。

  各インシデントでは、両側それぞれ最大 100 行、合計 64 KB までのログ行を取得して保持します。行数だけではファイルサイズを制限できません。1 行のスタックトレースや JSON ドキュメントはどれほど長くなることもあり、コンテナが OOM によって強制終了される場合には、まさにそのようなログが出力される可能性があります。ログが収まらない場合は末尾を保持します。プロセスが最後に出力した内容こそ停止理由の説明になるためです。また、破棄された量も示します。

これらの設定は、正規の形式である watch.notify: ブロックの下に記述することもできます。

watch:
  notify:
    enabled: true
    notify_on: flapping
    cooldown: 5m
  flapping:
    short_window: 10m

どちらの形式も読み込まれるため、どちらの配置でも動作します。ファイルに両方がある場合は notify: ブロックが優先され、その旨が homebutler config validate で通知されます。

ターゲットの管理

homebutler watch remove nginx           # Stop watching
homebutler watch check                  # One-shot check (no continuous monitoring)

アラートのしきい値（詳細）

CPU、メモリ、ディスクのしきい値チェックには引き続き alerts を使用できますが、これは詳細なワークフローであり、新規ユーザーに推奨される最初の手順ではありません。

homebutler alerts --watch                  # default: 30s interval
homebutler alerts --watch --interval 10s   # check every 10 seconds
homebutler alerts history                  # view alert history
homebutler notify test                     # test your notification channels

デフォルトのしきい値は、CPU 90％、メモリ 85％、ディスク 90％です。まず watch を使い、しきい値ベースのチェックが特に必要な場合にのみ alerts を追加してください。

バックアップと復元

Docker のバックアップを 1 つのコマンドで実行できます。ボリューム、Compose ファイル、環境変数が対象です。

homebutler backup                          # backup everything
homebutler backup --service jellyfin       # specific service
homebutler backup --to /mnt/nas/backups/   # custom destination
homebutler backup list                     # list backups
homebutler restore ./backup.tar.gz         # restore

⚠️ データの整合性を保つため、バックアップの前にデータベースサービスを一時停止してください。

📖 バックアップに関するドキュメント全文 → — 動作の仕組み、アーカイブの構成、セキュリティに関する注意事項を説明します。

🔍 バックアップドリル

「バックアップがあること」と「復元できること」は別です。

バックアップドリルは、隔離された Docker 環境でバックアップを起動し、アプリが実際に応答することを検証します。データのための避難訓練のようなものです。ドリルに失敗すると、ゼロ以外の終了コードで終了します。

homebutler backup drill uptime-kuma        # verify one app
homebutler backup drill --all              # verify all apps
homebutler backup drill --json             # machine-readable output
homebutler backup drill --archive ./file   # use a specific backup

合格したドリルでも証明できないことを含む詳しい手順については、docs/backup.md をご覧ください。

実行内容：

1. 最新のバックアップアーカイブを検出します
2. アーカイブの整合性を検証します（tar による検証）
3. 隔離された Docker ネットワークとランダムなポートを作成します
4. バックアップデータからアプリを起動します
5. HTTP ヘルスチェックを実行します
6. 成功／失敗を報告し、すべてをクリーンアップします

🔍 Backup Drill — uptime-kuma

  📦 Backup: ~/.homebutler/backups/backup_2026-04-04_1711.tar.gz
  📏 Size: 18.6 MB
  🔐 Integrity: ✅ tar valid (8 files)

  🚀 Boot: ✅ container started in 0s
  🌐 Health: ✅ HTTP 200 on port 58574
  ⏱️  Total: 2s

  ✅ DRILL PASSED

リスクはゼロ — 完全に隔離された環境で実行されます。稼働中のサービスには一切触れません。

次のアプリのヘルスチェックに対応しています：nginx-proxy-manager、vaultwarden、uptime-kuma、pi-hole、gitea、jellyfin、plex、portainer、homepage、adguard-home。

アプリのインストール

$ homebutler install list
📦 Available apps (15):

  uptime-kuma          A self-hosted monitoring tool
  vaultwarden          Lightweight Bitwarden-compatible password manager
  jellyfin             Free software media system for streaming movies, TV, and music
  pi-hole              Network-wide ad blocking via DNS filtering
  …

homebutler install uptime-kuma — セルフホストアプリを数秒でデプロイできます。Docker、ポート、重複を事前に確認します。docker-compose.yml を自動生成します。利用可能なすべてのアプリを見る →

1つのコマンドでセルフホストアプリをデプロイできます。各アプリは、事前チェック、ヘルス検証、適切なライフサイクル管理を自動で行い、docker compose で実行されます。

# List available apps
homebutler install list

# Install (default port)
homebutler install uptime-kuma

# Install with custom port
homebutler install uptime-kuma --port 8080

# Install jellyfin with media directory
homebutler install jellyfin --media /mnt/movies

# Check status
homebutler install status uptime-kuma

# Stop (data preserved)
homebutler install uninstall uptime-kuma

# Stop + delete everything
homebutler install purge uptime-kuma

動作の仕組み

~/.homebutler/apps/
  └── uptime-kuma/
       ├── docker-compose.yml   ← auto-generated, editable
       └── data/                ← persistent data (bind mount)

• 事前チェック — docker がインストール済みで実行中か、ポートが使用可能か、重複するコンテナがないかを確認します
• Compose ベース — 各アプリに専用の docker-compose.yml が用意され、内容を確認してカスタマイズできます
• データの安全性 — uninstall はコンテナを停止しますが、データは保持します。purge は、アプリが使用した Docker ボリュームを含め、すべてを削除し、ボリュームに名前を付けます。現時点での例外が1つあります。filebrowser のアカウントと設定は、uninstall 後に再インストールしても保持されません（表をご覧ください）
• クロスプラットフォーム — Docker ソケット（デフォルト、colima、podman）を自動検出します

利用可能なアプリ

アプリ固有のオプション

# Jellyfin: mount your media library
homebutler install jellyfin --media /mnt/movies

# Pi-hole / AdGuard: DNS ad blocking (port 53 required)
homebutler install pi-hole
# ⚠️ If port 53 is in use (Linux): sudo systemctl disable --now systemd-resolved

# Portainer: Docker GUI (mounts docker socket)
homebutler install portainer
# Access via HTTPS: https://localhost:9443

# Nginx Proxy Manager: reverse proxy
homebutler install nginx-proxy-manager
# Default login: [email protected] / changeme (change immediately!)

# Any app: custom port
homebutler install <app> --port 9999

安全性チェック

• ポート競合の検出 — インストール前に、ポートがすでに使用中かどうかを確認します
• DNS の同時使用防止 — pi-hole と adguard-home が両方インストールされている場合に警告します
• Docker ソケットの警告 — Docker ソケットへのアクセスが必要なアプリ（portainer）について警告します
• OS 固有のガイダンス — Linux では systemd-resolved の修正方法を、macOS では lsof コマンドを案内します
• インストール後のヒント — DNS の設定、HTTPS アクセス、デフォルト認証情報に関する警告を案内します

アプリを追加してほしい場合は、issue を作成するか、コントリビューションをご覧ください。

ダッシュボード

🌐 Web Dashboard

homebutler serve — go:embed を使って単一のバイナリに組み込まれた Web ダッシュボードです。任意のブラウザーから、サーバー、Docker コンテナー、開いているポート、アラート、Wake-on-LAN を確認できます。--token を指定すると、しきい値、通知チャネル、サーバー、Proxmox エンドポイント、ウェイクデバイスの設定も編集できます。

実際にレポートを読む Report タブ

通知を受け取った後に開く画面です。まず注意が必要な項目、次に変更内容とそれぞれに添えられたひと言、そして比較対象のスナップショットとその経過時間を表示します。比較できなかった場合は、問題がないかのように見せず、その旨を表示します。

読み込んでも何も保存されません。開くたびにスナップショットを取得すると、比較したかったベースラインが削除されてしまうためです。保存するにはボタンを押します。

homebutler serve              # Start on port 8080
homebutler serve --port 3000  # Custom port
homebutler serve --demo       # Demo mode with realistic sample data
homebutler serve install      # Let the host keep it running

🖥️ TUI ダッシュボード

homebutler watch tui — Bubble Tea を使用したターミナルベースのダッシュボードです。設定済みのすべてのサーバーをリアルタイムで監視し、色分けされたリソースバーと Docker コンテナーの状態を表示します。ブラウザーは不要です。

🗺️ インベントリーとトポロジー

homebutler inventory scan
homebutler inventory show --filter exposed
homebutler inventory export --format mermaid
homebutler --json inventory scan

inventory scan を使うと、サーバー上で稼働しているものをすばやく把握できます。システムの健全性、Docker コンテナー、アプリのポート、システムポートを確認できます。Docker が公開したポートは、そのポートを所有するコンテナーに関連付けられるため、Colima／Lima などのローカルフォワーディングの詳細もわかりやすくなります。

🏠 Home Network
   Server  homelab (192.168.1.10)
   Summary ✅ 1 running · ⚪ 1 stopped · 🌍 2 public ports · 🔒 4 local ports

📦 Containers (2)
   ├─ ⚪ vaultwarden · not started
   │  └─ image vaultwarden/server:latest
   └─ ✅ api-server · running
      ├─ image my-api:latest
      └─ exposes :8080 → 8080/tcp

🌐 App Ports (1)
   └─ 🌍 :8080/tcp · api-server

ツリー全体を確認せずに「自分のマシン／ネットワークの外部から到達できるものは何か」を知りたい場合は、スキャン結果を公開ポートのみに絞り込みます。

homebutler inventory scan --filter exposed

🏠 Home Network
   Server  homelab

🌐 Exposed Ports
   ├─ :8080/tcp · api-server
   └─ :8443/tcp · dashboard

すべてのインターフェース（0.0.0.0、::、*）で待ち受けているポートのみが表示されます。ループバックや LAN のアドレスを含め、特定のアドレスにバインドされたものは表示されません。サポートされていないフィルター値を指定した場合や、--filter と --json を併用した場合はエラーになります。デフォルトの inventory scan の出力は変わりません。

GitHub、Obsidian、ドキュメント、または AI アシスタント向けの図を作成する場合は、Mermaid エクスポートを使用します。

graph TD
  home["🏠 Home Network"] --> homelab["🖥 homelab<br/>192.168.1.10"]
  homelab --> c1["📦 api-server<br/>running"]
  homelab --> p1["🌍 :8080/tcp<br/>api-server"]
  c1 -. exposes .-> p1

🧊 Proxmox VE

homebutler proxmox status
homebutler proxmox guests --status running
homebutler proxmox guest shutdown --node pve1 --type lxc --vmid 105 --confirm
homebutler proxmox task UPID:pve1:... --node pve1

Proxmox エンドポイントは独自のターゲットとして扱われ、SSH ではなく API トークンを使って proxmox: の下に設定します。そのため、--server や --all の一括実行には含まれません。 TLS 検証は有効なままです。信頼の確認には、固定された SHA-256 フィンガープリント、CA ファイルの順に使用し、それらがない場合にのみ明示的な insecure フォールバックを使います。

読み取り操作は通常どおりです。一方、電源操作には制約があります。いずれの操作にも、エンドポイント、ノード、ゲストの種類、VMIDを明示する必要があり、--confirm を指定しないと実行されません。この確認は、認証情報を読み取る前に行われます。また、エンドポイントに専用の action_token_id（および action_token または action_token_file）を設定する必要があります。読み取り用トークンだけでは、ゲストの起動、再起動、シャットダウンは行えません。2つ目のトークンの作成方法については、Proxmox のセットアップ →を参照してください。 shutdown はゲストに正常なシャットダウンを要求します。電源を切断してファイルシステムに影響を残す可能性がある、Proxmox の強制的な stop とは異なります。操作が成功すると、送信したタスクが報告されますが、ゲストの処理が完了したことを示すものではありません。完了状況は proxmox task で個別に確認できます。

proxmox script は、特定のコミットに固定された Community Script のインストールコマンドを出力し、そのスクリプトは homebutler によるレビューを受けておらず、root として実行されるという警告も表示します。スクリプトを取得したり実行したりすることはありません。その理由については #62 を参照してください。

📖 Proxmox のセットアップ、トークン、TLS →

インストール

Homebrew（推奨）

brew install Higangssh/homebutler/homebutler

PATH に自動的にインストールされます。macOS と Linux で動作します。

1行インストール

curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh

OS とアーキテクチャを自動検出し、最新リリースをダウンロードして PATH にインストールします。

npm（MCP サーバー）

npm install -g homebutler

Go バイナリを自動的にダウンロードします。このパッケージが公開するコマンドは homebutler-mcp の1つだけで、MCP サーバーを起動します。npx -y homebutler@latest が起動するのは CLI ではなく、MCP サーバーです。コマンドラインで使う場合は、上記のほかのインストール方法を利用してください。

Go でインストール

go install github.com/Higangssh/homebutler@latest

ソースからビルド

git clone https://github.com/Higangssh/homebutler.git
cd homebutler
make build-all

make build-all は Web ダッシュボードをバイナリにコンパイルするため、Node のインストールが必要です。make build はダッシュボードを含めずにビルドします。どちらでも CLI は完全に利用でき、後者の場合は homebutler serve の実行時に、ダッシュボードが見つからないことと、入手方法が2つあることが表示されます。

アンインストール

rm $(which homebutler)           # Remove binary
rm -rf ~/.config/homebutler      # Remove config (optional)

使用方法

homebutler <command> [flags]

Commands:
  status              System status (CPU, memory, disk, uptime)
  doctor              Diagnose health, exposure, backups, and readiness
  config validate     Check the config file and report what is ignored
  docker list         List running containers
  install <app>       Install a self-hosted app (docker compose)
  alerts              Show current alert status
  watch tui           TUI dashboard (monitors all configured servers)
  watch add/list/remove  Manage watched containers
  watch check/start   One-shot or continuous restart detection
  watch history/show  Browse restart history
  proxmox status      Proxmox VE cluster, nodes, guests, and storage
  serve               Web dashboard (browser-based, go:embed)

Flags:
  --json              JSON output (default: human-readable)
  --verbose, -v       Show detailed error information
  --server <name>     Run on a specific remote server
  --all               Run on all configured servers in parallel
  --port <number>     Port for serve command (default: 8080)
  --config <path>     Config file (auto-detected, see Configuration)

すべてのコマンドを確認するには、homebutler --help を実行してください。

Commands:
  init                Interactive setup wizard
  config validate     Check the config file and report what is ignored
  status              System status (CPU, memory, disk, uptime)
  doctor              Diagnose health, exposure, backups, and readiness
  watch tui           TUI dashboard (monitors all configured servers)
  watch add <name>    Add container to restart watch list
  watch list          Show watched containers
  watch remove <name> Remove container from watch list
  watch check         One-shot restart check
  watch start         Continuous monitoring: restarts, thresholds, rules
  watch install       Register watch with systemd or launchd
  watch installed     Report whether it is registered
  watch uninstall     Remove the service unit
  watch history       List restart history (alias: incidents)
  watch show <id>     Show restart details with logs
  serve               Web dashboard (browser-based, go:embed)
  docker list         List running containers
  docker restart <n>  Restart a container
  docker stop <n>     Stop a container
  docker logs <n>     Show container logs
  docker top <n>      Show processes running inside a container
  docker inspect <n>  Show image, state, ports, mounts, networks, health
  report              What changed since the last snapshot
  inventory scan      Map containers, ports, and topology
  inventory show      Same as scan (--filter exposed narrows it)
  inventory export    Export the map (--format mermaid)
  proxmox status      Proxmox VE cluster, nodes, guests, storage
  proxmox guests      List QEMU and LXC guests
  proxmox node <n>    Node detail
  proxmox guest ...   start / shutdown / reboot (needs --confirm)
  proxmox task <upid> Task status for an action already submitted
  proxmox tasks       Recent tasks on a node
  proxmox script      Community Script install commands (prints, never runs)
  notify test         Send a test notification through configured providers
  wake <name>         Send Wake-on-LAN packet
  ports               List open ports with process info
  ps                  Show top processes (alias: processes)
  ps --sort mem       Sort by memory instead of CPU
  ps --limit 20       Show top 20 (default: 10, 0 = all)
  network scan        Discover devices on LAN
  alerts              Show current alert status
  alerts --watch      Thresholds only (watch start covers these too)
  trust <server>      Register SSH host key (TOFU)
  backup              Backup Docker volumes, compose files, and env
  backup list         List existing backups
  backup drill <app>  Verify backup restores correctly (isolated)
  backup drill --all  Verify all apps in backup
  restore <archive>   Restore from a backup archive
  upgrade             Upgrade local + all remote servers to latest
  deploy              Install homebutler on remote servers
  install <app>       Install a self-hosted app (docker compose)
  install list        List available apps
  install status <a>  Check installed app status
  install uninstall   Stop app (keep data)
  install purge       Stop app + delete all data
  mcp                 Start MCP server (JSON-RPC over stdio)
  version             Print version

Flags:
  --json              JSON output (default: human-readable)
  --verbose, -v       Show detailed error information
  --server <name>     Run on a specific remote server
  --all               Run on all configured servers in parallel
  --port <number>     Port for serve command (default: 8080)
  --demo              Run serve with realistic demo data
  --watch             Continuous monitoring mode (alerts command)
  --interval <dur>    Watch interval, e.g. 30s, 1m (default: 30s)
  --config <path>     Config file (auto-detected, see Configuration)
  --local             Upgrade only the local binary (skip remote servers)
  --local <path>      Use local binary for deploy (air-gapped)
  --service <name>    Target a specific Docker service (backup/restore)
  --allow-bind <path> Host path a restore may write a bind mount to (repeatable)
  --endpoint <name>   Proxmox endpoint from config (optional if only one)
  --confirm           Required for a Proxmox guest power action
  --to <path>         Custom backup destination directory
  --archive <path>    Specific backup archive for drill
  --all               Verify all supported apps (backup drill)

homebutler serve                # http://localhost:8080
homebutler serve --port 3000    # custom port
homebutler serve --demo         # demo mode with sample data
homebutler serve install        # hand it to launchd or systemd, so it survives logout
homebutler serve uninstall      # and take it back

設定

homebutler init    # interactive setup wizard

📖 report の比較内容 → — どのような場合に行が表示されるか、意図的に表示されない項目は何か、その理由を説明します。

📖 設定の詳細 → — 設定ファイルの場所、監視／通知オプション、高度なアラートしきい値について説明します。

マルチサーバー

1台のマシンから SSH 経由で複数のサーバーを管理できます。

homebutler status --server rpi     # query specific server
homebutler status --all            # query all in parallel
homebutler deploy --server rpi     # install on remote server
homebutler upgrade                 # upgrade all servers

📖 マルチサーバーのセットアップ → — SSH 認証、設定例、デプロイとアップグレードについて説明します。

MCP サーバー

組み込みの MCP サーバーです。エージェントは解析が必要な文章ではなく、型付きの JSON、種類、対象、詳細を含む同じレポートを受け取ります。また、すべてのツールは読み取り、書き込み、破壊的操作のいずれかに分類されています。

自動化したい場合は、自然言語を使ってください。 MCP クライアントは homebutler のツールを呼び出して、サーバーの状態を確認したり、Docker コンテナを一覧表示したり、ポートを調べたり、運用ワークフローを実行したりできます。

{
  "mcpServers": {
    "homebutler": {
      "command": "npx",
      "args": ["-y", "homebutler@latest"]
    }
  }
}

Claude Desktop、ChatGPT、Cursor、Windsurf、およびあらゆる MCP クライアントで動作します。

エージェントに変更を加えさせず、状況を確認させるには、args に "--max-risk", "read" を追加してください。変更を加えるツールは提示されず、名前を指定して呼び出された場合も拒否されます。また、report はスナップショットを保存せずに実行されます。読み取りモードで停止するのは変更であり、読み取りではありません。ログやコンテナの詳細は引き続き表示されます。読み取り専用モードの対象 →

📖 MCP サーバーのセットアップ → — 対応クライアント、利用可能なツール、エージェントスキル。

アーキテクチャ

butler は監視し、伝える価値のあることを判断して、あなたまたはエージェントに伝えます。

何かが変化する → report がその内容を示して優先順位を付ける → 通知、ダッシュボード、または MCP 呼び出しが 同じ回答を届けます。

        ┌─────────┐  ┌─────────┐  ┌─────────┐
        │   CLI   │  │   MCP   │  │   Web   │
        │ stdout  │  │  stdio  │  │  :8080  │
        └────┬────┘  └────┬────┘  └────┬────┘
             └────────────┼────────────┘
                          ▼
                   internal/*
         system · docker · ports · network
         wake · alerts · remote (SSH)

3 つのインターフェース、1 つのコア：

3 つすべてが同じ internal/ パッケージを呼び出すため、コードの重複はありません。

エージェントは人間と同じレポートを読み取り、解釈しなければならない画面ではなく、分岐処理に必要な情報を受け取ります。

report = json.loads(subprocess.run(
    ["homebutler", "report", "--json"], capture_output=True, text=True).stdout)

for change in report["notable_changes"]:
    if change["kind"] == "replaced":         # the container came back as something else
        redeploy(change["target"])
    else:
        log(change["text"])                  # "port: :8080/tcp — nginx → caddy"

すべての行には text も含まれているため、出力だけを必要とする呼び出し元は、文章を組み立て直す必要がありません。何も見つからなかった実行では "notable_changes": [] が返されるため、静かな日には上記のループは何も行いません。

これらの処理は homebutler の管轄外です。MCP クライアント、チャットボット、cron の設定行、ターミナルを使う人のいずれからでも、同じ回答にたどり着きます。

デフォルトではポートを開きません。 CLI と MCP は標準入出力のみを使用します。Web ダッシュボードはオプトイン方式です（homebutler serve は 127.0.0.1 にバインドします）。

コントリビューション

コントリビューションを歓迎します。変更したい内容について、まず issue を作成して相談してください。 CONTRIBUTING.md では、homebutler が受け入れる内容と、新しいターゲットに求められる条件を説明しています。

セキュリティ

脆弱性を発見しましたか？公開 issue ではなく、 Security タブ から非公開で報告してください。SECURITY.md では、対象範囲と報告後の流れを説明しています。

ライセンス

MIT