macOSミニオンのセットアップ(旧版)
Mac(mini / Studio / MacBook など)に @geekbeer/minion を入れると、その Mac をミニオンとして使えます(セルフホスト)。ミニオンは専用の minion ユーザーで動きます。管理者権限(sudo)が要るのは最初のセットアップとアンインストールだけで、普段の操作は minion ユーザーで行えます。
準備するもの
Section titled “準備するもの”Homebrew
Section titled “Homebrew”セットアップは Homebrew を使います。入っていないとセットアップは最初に止まるので、先に入れておいてください。
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"入れたあとは、表示される案内に従って ~/.zprofile に brew shellenv を追記するか、ターミナルを開き直してください。
Node.js 22 以上
Section titled “Node.js 22 以上”Homebrew で入れてください。
brew install node管理者ユーザー
Section titled “管理者ユーザー”セットアップは、管理者権限を持つユーザーから実行します。
FileVault と自動ログイン
Section titled “FileVault と自動ログイン”ミニオンは minion ユーザーがログインしている間だけ動きます。Mac を再起動しても動き続けるには、minion ユーザーの自動ログインが必要です。ところが FileVault が有効だと、macOS は自動ログインを許可しません。運用に合わせて選んでください。
- 24時間動かしたい場合 — FileVault を無効にし、
minionユーザーの自動ログインを有効にする - 再起動のたびに手でログインしてよい場合 — FileVault は有効のままでよい
スリープと停電(24時間動かす場合)
Section titled “スリープと停電(24時間動かす場合)”セットアップが止めるのはディスプレイのスリープだけで、Mac 本体のスリープは止めません。24時間動かす場合は、本体がスリープしないように、また停電から復旧したら自動で起動するように設定しておきます。
sudo pmset -a sleep 0 # 本体をスリープさせないsudo pmset -a autorestart 1 # 停電のあと自動で起動する(対応している機種のみ)セットアップ
Section titled “セットアップ”1. HQ でミニオンを登録する
Section titled “1. HQ でミニオンを登録する”サイドバーの ミニオン を開き、ミニオンを追加 から Self-host VPS を選び、ミニオンを登録 を押します(説明には Ubuntu / Debian とありますが、Mac でもこれを選びます)。
登録すると、実行するコマンドが表示されます。macOS を選んでコピーしてください。Linux のコマンドは Mac では動きません。同じコマンドは、あとからミニオンの詳細画面の セットアップコマンド でも確認できます。
2. パッケージを入れる(管理者ユーザー)
Section titled “2. パッケージを入れる(管理者ユーザー)”npm install -g @geekbeer/minionEACCES: permission denied が出る場合は、Node.js を公式インストーラで入れています。Node.js 22 以上 を参照して Homebrew の Node.js に切り替えてください。
3. セットアップを実行する(管理者ユーザー)
Section titled “3. セットアップを実行する(管理者ユーザー)”sudo minion-cli-mac setup --user minionminion ユーザーがまだ無い場合は、パスワードを聞かれて作成されます。自動ログインと画面共有にはパスワードが必要なので、空にはできません。
セットアップは次のことを行います(数分かかります)。
minionユーザーを作る- Homebrew で必要なもの(tmux、ttyd、jq、node、cloudflared)を入れる
- Claude Code と Gemini CLI を入れる
- 画面共有を有効にし、VNC のパスワードを設定する。パスワードは自動で作られ、この Mac の中にだけ保存されます
- スリープやスクリーンセーバーのあとのパスワードを求めないようにし、ディスプレイがスリープしないようにする
- ミニオンをログイン時に起動するよう登録する
4. システム設定で画面共有をオンにする
Section titled “4. システム設定で画面共有をオンにする”macOS Ventura 以降は、セットアップだけでは画面共有がオンになりません。システム設定 → 一般 → 共有 → 画面共有 をオンにしてください。
オンになったかどうかは、次のコマンドで確かめられます。LISTEN の行が出ればオンです。
netstat -an -p tcp | grep '\.5900 'lsof -iTCP:5900 では確かめられません。画面共有のプロセスは管理者の権限で動いているので、sudo を付けないとオンでも何も表示されません。
5. 自動ログインを有効にする(24時間動かす場合)
Section titled “5. 自動ログインを有効にする(24時間動かす場合)”システム設定 → ユーザとグループ → 自動ログイン で minion を選びます。FileVault が有効だと、この項目は表示されません(FileVault と自動ログイン)。
6. HQ に接続する(minion ユーザー)
Section titled “6. HQ に接続する(minion ユーザー)”minion ユーザーに切り替えて、HQ が表示したコマンドの後半(configure)を実行します。
sudo su - minion
minion-cli-mac configure \ --hq-url https://<HQ の URL> \ --minion-id <ミニオン ID> \ --api-token <API トークン> \ --setup-tunnel--setup-tunnel は外さないでください。 HQ はこのトンネルを通ってミニオンにつながるので、外すと HQ からターミナル・画面・ファイルが使えません。HQ が表示するコマンドには含まれています。
su には必ず - を付けてください(sudo su - minion)。付けないと minion ユーザーの PATH が読み込まれず、minion-cli-mac が見つかりません。
7. AI にサインインする
Section titled “7. AI にサインインする”ミニオンが仕事をするには、AI(LLM)を使えるようにしておく必要があります。HQ のミニオンの画面から画面共有(VNC)で minion ユーザーとして Mac に入り、ターミナルで claude を実行してサインインしてください。使う AI を切り替える方法は LLMプラグイン を参照してください。
8. 確かめる
Section titled “8. 確かめる”ミニオン ページで、ミニオンがオンラインになっていれば完了です。Mac の側でも確かめられます(minion ユーザーで実行)。
minion-cli-mac status # ミニオンの状態minion-cli-mac health # ヘルスチェックminion ユーザーで実行します。
minion-cli-mac status # ミニオンの状態minion-cli-mac health # ヘルスチェックminion-cli-mac daemons # ミニオンの中で動いている処理(ボードの監視など)の状態minion-cli-mac diagnose # 詳しい診断minion-cli-mac restart # ミニオンを再起動するminion-cli-mac stop # ミニオンを止めるminion-cli-mac start # ミニオンを起動するminion-cli-mac --version # バージョンrestart / stop / start が扱うのはミニオン本体だけです。画面共有の中継や HQ との接続(cloudflared)は止まりません。
tail -f ~/.minion/logs/agent.out.logtail -f ~/.minion/logs/agent.err.logtail -f ~/.minion/logs/vnc-proxy.out.log # 画面共有の中継tail -f ~/.minion/logs/cloudflared.err.log # HQ との接続HQ のミニオンの詳細画面に v〜 に更新 が出ていたら、それを押すと更新されます。
HQ の Re-register で接続情報を作り直した場合は、表示されたコマンドで configure をもう一度実行します。このとき、コマンドに --setup-tunnel が無ければ付け足してください。
セットアップ(setup)は、何度実行しても既存の接続情報を消しません。何かが入っていない・壊れたというときは、もう一度実行して直せます。
アンインストール
Section titled “アンインストール”管理者ユーザーで実行します。確認を求められるので yes と入力します。
sudo minion-cli-mac uninstall --user minion # --keep-data を付けるとミニオンのデータ(~/.minion)を残すnpm uninstall -g @geekbeer/minion次のものは残ります。不要なら手で戻してください。
minionユーザー(システム設定 → ユーザとグループ から削除)- Homebrew で入れたもの
- 画面共有(オンのまま)と、スリープ・スクリーンセーバー・ディスプレイの設定
minionユーザーの~/.zprofileに追記された行
ディスプレイをつながずに使う
Section titled “ディスプレイをつながずに使う”Mac mini をディスプレイなしで置くと、画面共有が映す画面が無いため、HQ の画面共有が真っ黒になります。
HDMI ダミープラグ(ヘッドレスディスプレイアダプタ)を HDMI 端子に挿すと、macOS がディスプレイがつながっていると認識し、画面共有が映るようになります。数百円から手に入り、設定の変更は要りません。画面が縮んだり拡大されたりして映る場合は、システム設定 → ディスプレイ で解像度を変えてください。
npm install -g で EACCES: permission denied が出る
Section titled “npm install -g で EACCES: permission denied が出る”npm error code EACCESnpm error syscall mkdirnpm error path /usr/local/lib/node_modules/@geekbeernpm error errno -13公式サイトのインストーラ(.pkg)で入れた Node.js を使っています。取り除いてから Homebrew で入れ直してください。
公式 .pkg 版の Node.js を取り除く
Section titled “公式 .pkg 版の Node.js を取り除く”# 本体sudo rm -rf /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npxsudo rm -rf /usr/local/include/node /usr/local/lib/node_modulessudo rm -rf /usr/local/lib/dtrace/node.dsudo rm -rf /usr/local/share/man/man1/node.1sudo rm -rf /usr/local/share/doc/nodesudo rm -rf /usr/local/share/systemtap/tapset/node.stp
# インストールの記録sudo rm -rf /var/db/receipts/org.nodejs.*
# ユーザーのキャッシュと設定rm -rf ~/.npm ~/.node-gyp ~/.npmrcそのあと brew install node で入れ直します。
セットアップで「User exists but has NO PASSWORD set」と出る
Section titled “セットアップで「User exists but has NO PASSWORD set」と出る”minion ユーザーにパスワードが設定されていません。自動ログインと画面共有にはパスワードが必要なので、設定してからセットアップをやり直してください。
sudo dscl . -passwd /Users/minionセットアップで「cannot prompt for password (non-interactive shell)」と出る
Section titled “セットアップで「cannot prompt for password (non-interactive shell)」と出る”パスワードを入力できない環境(スクリプトやバックグラウンドなど)からセットアップを実行しています。ターミナルから直接 実行するか、先にユーザーを作ってから実行してください。
sudo sysadminctl -addUser minion -fullName "Minion Agent" -password "YOUR_PASSWORD"sudo minion-cli-mac setup --user minionconfigure で「.env not found」と出る
Section titled “configure で「.env not found」と出る”configure を minion ユーザー以外で実行しています。sudo su - minion で切り替えてから実行してください。
minion-cli-mac が見つからない
Section titled “minion-cli-mac が見つからない”minion ユーザーに - なしで切り替えています。sudo su - minion のように - を付けると、minion ユーザーの設定(~/.zprofile)が読み込まれて見つかるようになります。
HQ のターミナルで claude: command not found と出る
Section titled “HQ のターミナルで claude: command not found と出る”古いバージョン(5.10.0 より前)でセットアップした Mac で起きます。ミニオンを更新してから sudo minion-cli-mac setup --user minion をもう一度実行し、HQ で新しいターミナルを開いてください(開いたままのターミナルは古い設定のままです)。
画面共有が真っ黒になる
Section titled “画面共有が真っ黒になる”ディスプレイがつながっていません。HDMI ダミープラグを挿すか、ディスプレイをつないでください(ディスプレイをつながずに使う)。
画面共有が認証エラーでつながらない
Section titled “画面共有が認証エラーでつながらない”ミニオンが保存している VNC のパスワードと、macOS の画面共有のパスワードが食い違っています。セットアップをもう一度実行するか、管理者ユーザーで次を実行して合わせ直してください。
VNC_PW=$(sudo awk -F'=' '/^VNC_PASSWORD=/{print $2}' /Users/minion/.minion/.env)sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/Resources/kickstart \ -configure -clientopts -setvnclegacy -vnclegacy yes -setvncpw -vncpw "$VNC_PW"diagnose で TUNNEL が FAIL になる
Section titled “diagnose で TUNNEL が FAIL になる”HQ との接続(Cloudflare Tunnel)は、configure に --setup-tunnel を付けたときだけ設定されます。minion ユーザーで原因を確かめてください。
# 1. 設定されているかhead -3 ~/.cloudflared/config.yml
# 2. 動いているかlaunchctl print gui/$(id -u)/com.geekbeer.cloudflared | grep state
# 3. 止まった理由tail -30 ~/.minion/logs/cloudflared.err.log| 症状 | 対処 |
|---|---|
config.yml が無い | --setup-tunnel を付けて configure をやり直す |
credentials-file が /etc/cloudflared/... を指している | 古いバージョンで設定したミニオンです。更新してから configure をやり直す |
Could not find service | minion ユーザーが画面にログインしていません。自動ログインを有効にして minion でログインしてから、やり直す(ssh や su - で入ったシェルでは起動できません) |
ミニオンが起動しない
Section titled “ミニオンが起動しない”ミニオンは、minion ユーザーが 画面にログインしている間だけ 動きます。ログインしているかを確かめてください。
# minion ユーザーの UID を調べるdscl . -read /Users/minion UniqueID
# その UID でログインしているかlaunchctl print gui/<UID> | head -5ログインしていなければ、minion で Mac に直接ログインするか、画面共有からログインするか、自動ログインを有効にしてください。
自動ログインが効かない
Section titled “自動ログインが効かない”FileVault が有効になっている可能性があります。
fdesetup statusFileVault is On. と出る場合、macOS の仕様で自動ログインは使えません。FileVault を無効にするか、再起動のたびに手でログインしてください。
問い合わせ用にセットアップの記録を取る
Section titled “問い合わせ用にセットアップの記録を取る”tee を使うと出力が溜まって止まったように見えることがあるので、script を使ってください。
script -q /tmp/minion-setup.log sudo minion-cli-mac setup --user minionさらに詳しい記録が必要なときは、MINION_TRACE=1 を付けると実行したコマンドをすべて出力します。
sudo MINION_TRACE=1 minion-cli-mac setup --user minion 2> /tmp/minion-trace.log