コンテンツにスキップ

macOSミニオンのセットアップ(旧版)

Mac(mini / Studio / MacBook など)に @geekbeer/minion を入れると、その Mac をミニオンとして使えます(セルフホスト)。ミニオンは専用の minion ユーザーで動きます。管理者権限(sudo)が要るのは最初のセットアップとアンインストールだけで、普段の操作は minion ユーザーで行えます。

セットアップは Homebrew を使います。入っていないとセットアップは最初に止まるので、先に入れておいてください。

Terminal window
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

入れたあとは、表示される案内に従って ~/.zprofile に brew shellenv を追記するか、ターミナルを開き直してください。

Homebrew で入れてください。

Terminal window
brew install node

セットアップは、管理者権限を持つユーザーから実行します。

ミニオンは minion ユーザーがログインしている間だけ動きます。Mac を再起動しても動き続けるには、minion ユーザーの自動ログインが必要です。ところが FileVault が有効だと、macOS は自動ログインを許可しません。運用に合わせて選んでください。

  • 24時間動かしたい場合 — FileVault を無効にし、minion ユーザーの自動ログインを有効にする
  • 再起動のたびに手でログインしてよい場合 — FileVault は有効のままでよい

スリープと停電(24時間動かす場合)

Section titled “スリープと停電(24時間動かす場合)”

セットアップが止めるのはディスプレイのスリープだけで、Mac 本体のスリープは止めません。24時間動かす場合は、本体がスリープしないように、また停電から復旧したら自動で起動するように設定しておきます。

Terminal window
sudo pmset -a sleep 0 # 本体をスリープさせない
sudo pmset -a autorestart 1 # 停電のあと自動で起動する(対応している機種のみ)

サイドバーの ミニオン を開き、ミニオンを追加 から Self-host VPS を選び、ミニオンを登録 を押します(説明には Ubuntu / Debian とありますが、Mac でもこれを選びます)。

登録すると、実行するコマンドが表示されます。macOS を選んでコピーしてください。Linux のコマンドは Mac では動きません。同じコマンドは、あとからミニオンの詳細画面の セットアップコマンド でも確認できます。

2. パッケージを入れる(管理者ユーザー)

Section titled “2. パッケージを入れる(管理者ユーザー)”
Terminal window
npm install -g @geekbeer/minion

EACCES: permission denied が出る場合は、Node.js を公式インストーラで入れています。Node.js 22 以上 を参照して Homebrew の Node.js に切り替えてください。

3. セットアップを実行する(管理者ユーザー)

Section titled “3. セットアップを実行する(管理者ユーザー)”
Terminal window
sudo minion-cli-mac setup --user minion

minion ユーザーがまだ無い場合は、パスワードを聞かれて作成されます。自動ログインと画面共有にはパスワードが必要なので、空にはできません。

セットアップは次のことを行います(数分かかります)。

  • minion ユーザーを作る
  • Homebrew で必要なもの(tmux、ttyd、jq、node、cloudflared)を入れる
  • Claude Code と Gemini CLI を入れる
  • 画面共有を有効にし、VNC のパスワードを設定する。パスワードは自動で作られ、この Mac の中にだけ保存されます
  • スリープやスクリーンセーバーのあとのパスワードを求めないようにし、ディスプレイがスリープしないようにする
  • ミニオンをログイン時に起動するよう登録する

4. システム設定で画面共有をオンにする

Section titled “4. システム設定で画面共有をオンにする”

macOS Ventura 以降は、セットアップだけでは画面共有がオンになりません。システム設定 → 一般 → 共有 → 画面共有 をオンにしてください。

オンになったかどうかは、次のコマンドで確かめられます。LISTEN の行が出ればオンです。

Terminal window
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)を実行します。

Terminal window
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 が見つかりません。

ミニオンが仕事をするには、AI(LLM)を使えるようにしておく必要があります。HQ のミニオンの画面から画面共有(VNC)で minion ユーザーとして Mac に入り、ターミナルで claude を実行してサインインしてください。使う AI を切り替える方法は LLMプラグイン を参照してください。

ミニオン ページで、ミニオンがオンラインになっていれば完了です。Mac の側でも確かめられます(minion ユーザーで実行)。

Terminal window
minion-cli-mac status # ミニオンの状態
minion-cli-mac health # ヘルスチェック

minion ユーザーで実行します。

Terminal window
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)は止まりません。

Terminal window
tail -f ~/.minion/logs/agent.out.log
tail -f ~/.minion/logs/agent.err.log
tail -f ~/.minion/logs/vnc-proxy.out.log # 画面共有の中継
tail -f ~/.minion/logs/cloudflared.err.log # HQ との接続

HQ のミニオンの詳細画面に v〜 に更新 が出ていたら、それを押すと更新されます。

HQ の Re-register で接続情報を作り直した場合は、表示されたコマンドで configure をもう一度実行します。このとき、コマンドに --setup-tunnel が無ければ付け足してください。

セットアップ(setup)は、何度実行しても既存の接続情報を消しません。何かが入っていない・壊れたというときは、もう一度実行して直せます。

管理者ユーザーで実行します。確認を求められるので yes と入力します。

Terminal window
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 EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/@geekbeer
npm error errno -13

公式サイトのインストーラ(.pkg)で入れた Node.js を使っています。取り除いてから Homebrew で入れ直してください。

公式 .pkg 版の Node.js を取り除く

Section titled “公式 .pkg 版の Node.js を取り除く”
Terminal window
# 本体
sudo rm -rf /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx
sudo rm -rf /usr/local/include/node /usr/local/lib/node_modules
sudo rm -rf /usr/local/lib/dtrace/node.d
sudo rm -rf /usr/local/share/man/man1/node.1
sudo rm -rf /usr/local/share/doc/node
sudo 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 ユーザーにパスワードが設定されていません。自動ログインと画面共有にはパスワードが必要なので、設定してからセットアップをやり直してください。

Terminal window
sudo dscl . -passwd /Users/minion

セットアップで「cannot prompt for password (non-interactive shell)」と出る

Section titled “セットアップで「cannot prompt for password (non-interactive shell)」と出る”

パスワードを入力できない環境(スクリプトやバックグラウンドなど)からセットアップを実行しています。ターミナルから直接 実行するか、先にユーザーを作ってから実行してください。

Terminal window
sudo sysadminctl -addUser minion -fullName "Minion Agent" -password "YOUR_PASSWORD"
sudo minion-cli-mac setup --user minion

configure で「.env not found」と出る

Section titled “configure で「.env not found」と出る”

configure を minion ユーザー以外で実行しています。sudo su - minion で切り替えてから実行してください。

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 で新しいターミナルを開いてください(開いたままのターミナルは古い設定のままです)。

ディスプレイがつながっていません。HDMI ダミープラグを挿すか、ディスプレイをつないでください(ディスプレイをつながずに使う)。

画面共有が認証エラーでつながらない

Section titled “画面共有が認証エラーでつながらない”

ミニオンが保存している VNC のパスワードと、macOS の画面共有のパスワードが食い違っています。セットアップをもう一度実行するか、管理者ユーザーで次を実行して合わせ直してください。

Terminal window
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"

HQ との接続(Cloudflare Tunnel)は、configure に --setup-tunnel を付けたときだけ設定されます。minion ユーザーで原因を確かめてください。

Terminal window
# 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 serviceminion ユーザーが画面にログインしていません。自動ログインを有効にして minion でログインしてから、やり直す(ssh や su - で入ったシェルでは起動できません)

ミニオンは、minion ユーザーが 画面にログインしている間だけ 動きます。ログインしているかを確かめてください。

Terminal window
# minion ユーザーの UID を調べる
dscl . -read /Users/minion UniqueID
# その UID でログインしているか
launchctl print gui/<UID> | head -5

ログインしていなければ、minion で Mac に直接ログインするか、画面共有からログインするか、自動ログインを有効にしてください。

FileVault が有効になっている可能性があります。

Terminal window
fdesetup status

FileVault is On. と出る場合、macOS の仕様で自動ログインは使えません。FileVault を無効にするか、再起動のたびに手でログインしてください。

問い合わせ用にセットアップの記録を取る

Section titled “問い合わせ用にセットアップの記録を取る”

tee を使うと出力が溜まって止まったように見えることがあるので、script を使ってください。

Terminal window
script -q /tmp/minion-setup.log sudo minion-cli-mac setup --user minion

さらに詳しい記録が必要なときは、MINION_TRACE=1 を付けると実行したコマンドをすべて出力します。

Terminal window
sudo MINION_TRACE=1 minion-cli-mac setup --user minion 2> /tmp/minion-trace.log