macOSミニオンのセットアップ

Mac (mini / Studio / MacBook 等) は @geekbeer/minion パッケージを使ってセルフホストミニオンとして運用できます。launchd ベースの LaunchAgent として登録され、HQ からの install / update / restart が動作します。初回セットアップ時のみ管理者権限（sudo）が必要で、以降の日常運用（start/stop/restart/status 等）は専用の minion ユーザーで実行できます。

アーキテクチャ

flowchart LR
    subgraph Mac["macOS"]
        CLI["minion-cli-mac"]
        Server["エージェント\n(Fastify :8080)"]
        Terminal["ttyd\n(:7681)"]
        Tmux["tmux セッション"]
        Claude["Claude Code CLI"]
        ScreenSharing["macOS Screen Sharing\n(:5900, native)"]
        VNCProxy["vnc-auth-proxy\n(Node, :6080)"]

        Server --> Tmux
        Terminal --> Tmux
        Tmux --> Claude
        VNCProxy --> ScreenSharing
    end

    subgraph Cloud["Cloud"]
        HQ["HQ Server"]
    end

    HQ <-->|HTTPS / Cloudflare Tunnel| Server
    HQ -->|WebSocket proxy| Terminal
    HQ -->|WebSocket proxy| VNCProxy

macOSミニオンと他プラットフォームの違い

項目	macOS	Windows	Linux
CLI	`minion-cli-mac` (Bash)	`minion-cli-win` (Node.js → PowerShell)	`minion-cli` (Bash)
サービスマネージャ	launchd (LaunchAgent)	NSSM (Windows Service)	systemd / supervisord
管理者権限	setup / uninstall のみ必要	setup / uninstall のみ必要	必要 (root)
エージェント実行ユーザー	`minion`（専用ユーザー、setup時に作成）	LocalSystem	`minion`（専用システムユーザー）
デスクトップ	ログインユーザー（auto-login 推奨）	ログオンユーザー (VNC=ログオンタスク)	`ubuntu`（Xvfb + VNC）
ターミナルセッション	tmux + ttyd	node-pty	tmux
データディレクトリ	`~/.minion/`（ターゲットユーザーのホーム）	`<target-user>\.minion\`	`/opt/minion-agent/`
VNC	macOS Screen Sharing + Node 製 vnc-auth-proxy	TightVNC + websockify	x11vnc + websockify

事前準備

Homebrew

minion-cli-mac setup の Step 2 が brew install に依存しているため、Homebrew が事前にインストールされている必要があります。

# 公式インストーラ
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Apple Silicon の場合は /opt/homebrew/、Intel の場合は /usr/local/ にインストールされます。インストール後、案内に従って ~/.zprofile に brew shellenv を追加するか、ターミナルを再起動してください。

Node.js 22 LTS

@geekbeer/minion は engines: ">=22.0.0" を要求します。Homebrew 経由でのインストールを推奨します。

brew install node

公式インストーラ（.pkg）は非推奨: /usr/local/lib/node_modules が root 所有になるため、npm install -g が EACCES: permission denied で失敗します。既に .pkg 版が入っている場合は、後述の公式 .pkg 版 Node.js を削除するを参照してください。

バージョン固定が必要な場合は nodenv (brew install nodenv) を使うとクリーンです。

管理者ユーザー

セットアップは admin 権限を持つユーザーから実行します。sudo で minion 専用ユーザーを作成し、各種設定を行います。

FileVault について

FileVault が有効だと auto-login が効きません。 macOS の仕様で、FileVault 有効時は起動時にディスク復号のためのログインが必須となり、その後の自動ログインは許可されません。LaunchAgent はユーザーがログインしている GUI セッションでのみ動作するため、運用形態に応じて以下を選択してください。

24時間稼働させたい場合: FileVault を無効化し、minion ユーザーで auto-login を有効化
手動起動でよい場合: FileVault を有効のまま、再起動後に手動で minion にログイン

セットアップ手順

1. HQ でミニオンを作成

HQ ダッシュボードから「新規ミニオン」を作成し、プロバイダタイプを Self-hosted に設定します。発行される minion_id と api_token を控えておきます。

2. パッケージをインストール（admin ユーザーで実行）

npm install -g @geekbeer/minion

EACCES: permission denied が出る場合: Node.js の入れ方の問題です。事前準備を参照して Homebrew 版に切り替えてください。

3. セットアップを実行（admin ユーザーで実行）

sudo minion-cli-mac setup --user minion

--user で指定したユーザーが存在しない場合、対話的にパスワード入力を求められて新規作成されます。auto-login と Screen Sharing の両方がパスワードを必須とするため、空パスワードでは作成できません。

セットアッププロセス（全14ステップ、所要時間 5〜15 分）:

ターゲットユーザーの作成・検証（sysadminctl -addUser）
Homebrew 依存パッケージのインストール（tmux, ttyd, jq, node, cloudflared）
Claude Code CLI のインストール（ターゲットユーザーとして）
Gemini CLI のインストール
~/.minion/, ~/.minion/logs/, ~/files/ ディレクトリの作成
ターゲットユーザーの .zprofile に brew shellenv を追記
.env 生成（VNC パスワードを自動生成）
sudoers 設定（ターゲットユーザーが特定コマンドを sudo 不要で実行できるように）
@geekbeer/minion のインストールパス検証
LaunchAgent plist 生成（tmux-init, agent, vnc-proxy）
macOS Screen Sharing の有効化 + VNC パスワード設定（ARD kickstart）
画面ロック・スクリーンセーバー・ディスプレイスリープの無効化
LaunchAgent のブートストラップ（ターゲットユーザーが GUI ログイン中の場合のみ）
バンドルされたスキル・ルールのデプロイ

セットアップ完了後の手動ステップ

setup スクリプトは完了時に以下の手動ステップを案内します。

(1) Screen Sharing をシステム設定で有効化（必須）

macOS Ventura 以降は TCC により launchctl enable だけでは有効化されません。

システム設定 → 一般 → 共有 → 画面共有 → ON

確認:

lsof -nP -iTCP:5900 -sTCP:LISTEN

(2) minion ユーザーで auto-login を有効化（24時間稼働する場合）

システム設定 → ユーザとグループ → 自動ログイン → minion

FileVault が ON の場合は項目自体が表示されません（前述の通り）。

(3) minion ユーザーに切り替えて HQ へ接続

# admin ユーザーから minion ユーザーへ切り替え（ログインシェルで PATH を読み込む）
sudo su - minion

# HQ への接続（sudo 不要）
minion-cli-mac configure \
  --hq-url https://<your-hq-url> \
  --minion-id <minion-id> \
  --api-token <api-token>

Configure プロセス:

.env に HQ 接続情報を書き込み
バンドルされたスキル・ルールをデプロイ
Cloudflare Tunnel の設定（--setup-tunnel 指定時）
LaunchAgent の再起動
ヘルスチェック + HQ への接続完了通知

権限モデル

sudo が必要なのは setup / uninstall のみです。日常運用は minion ユーザーで完結します。

コマンド	権限	仕組み
`setup`, `uninstall`	`sudo` 必須（admin から実行）	ユーザー作成、Homebrew install、sudoers 設定、LaunchAgent 配置
`configure`	`minion` ユーザー	.env 書き込み + スキルデプロイ + LaunchAgent 再起動 + HQ通知
`start`, `stop`, `restart`	`minion` ユーザー	`launchctl bootstrap/bootout/kickstart`（sudoers で許可済み）
`status`, `health`, `daemons`, `diagnose`	`minion` ユーザー	読み取りのみ

setup によって /etc/sudoers.d/minion-agent に以下が登録され、minion ユーザーが sudo 不要で特定コマンドを実行できます:

npm install -g @geekbeer/minion@latest（自己アップデート用）
brew install * / brew upgrade *（依存追加用）
launchctl kickstart -k * / bootstrap * / bootout *（サービス管理用）

VNC とスクリーン共有の仕組み

macOS ミニオンは Linux / Windows と異なり、macOS ネイティブの Screen Sharing（port 5900）を使い、Node.js 製の vnc-auth-proxy が WebSocket 化（port 6080）して HQ に提供します。

Browser (HQ) ─[WebSocket]─> vnc-auth-proxy.js (:6080) ─[RFB]─> screensharingd (:5900)

コンポーネント	説明
`screensharingd`	macOS 標準の VNC サーバー。`launchctl` で有効化、ARD `kickstart` で VNC パスワード設定
`vnc-auth-proxy.js`	LaunchAgent として常駐する Node スクリプト。`.env` の `VNC_PASSWORD` を使って screensharingd と RFB 認証を行い、HQ へは認証なし WebSocket として中継

v3.47.8 以前: websockify (Python) と noVNC web assets を使用していましたが、Node 製 proxy に置き換えられました。新規セットアップでは不要です。

VNC パスワードはランダム生成され、~/.minion/.env に保存されます（mode 0600）。HQ には送信されません。

動作確認

1. ステータス確認

# minion ユーザーで実行
minion-cli-mac status
minion-cli-mac daemons    # 全 LaunchAgent の状態

2. ヘルスチェック

minion-cli-mac health

3. HQ → ミニオンの疎通確認

LAN 内の別マシンから:

curl http://<mac-ip>:8080/api/status \
  -H "Authorization: Bearer <api-token>"

4. WebSocket（ターミナル / VNC）の動作確認

HQ ダッシュボードを開き、対象ミニオンの Terminal タブと VNC タブを開きます。

設定

環境変数ファイル

~/.minion/.env（minion ユーザーのホーム配下）:

AGENT_PORT=8080
MINION_USER=minion
HQ_URL=https://<your-hq-url>
API_TOKEN=<token>
MINION_ID=<uuid>
VNC_PASSWORD=<auto-generated>
REFLECTION_TIME=03:00

サービス管理

minion-cli-mac status     # エージェントステータス
minion-cli-mac health     # ヘルスチェック
minion-cli-mac daemons    # 全 LaunchAgent ステータス
minion-cli-mac restart    # 再起動
minion-cli-mac stop
minion-cli-mac start
minion-cli-mac diagnose   # 詳細診断

ログ

tail -f ~/.minion/logs/agent.out.log
tail -f ~/.minion/logs/agent.err.log
tail -f ~/.minion/logs/vnc-proxy.out.log

LaunchAgent plist

~/Library/LaunchAgents/ に以下が配置されます:

Label	説明
`com.geekbeer.minion.tmux-init`	ログイン時に `main` tmux セッションを作成
`com.geekbeer.minion.agent`	エージェント本体（Fastify + ttyd）
`com.geekbeer.minion.vnc-proxy`	VNC 認証プロキシ

ヘッドレス運用（ディスプレイなし）

Mac mini をヘッドレスで運用する場合、macOS Screen Sharing がミラーリングする物理ディスプレイが必要です。

推奨: HDMI ダミープラグ

HDMI ダミープラグ（ヘッドレスディスプレイアダプタ）を HDMI ポートに挿すと、OS がディスプレイ接続を認識し、Screen Sharing が正常に画面をキャプチャできるようになります。

Amazon 等で「HDMI ダミープラグ」で検索（数百円〜）
ソフトウェアの変更は不要
DPI スケーリングの注意点は Windowsミニオンを参照（macOS の場合 defaults write ではなくシステム設定 → ディスプレイから変更）

トラブルシューティング

npm install -g で `EACCES: permission denied` が出る

公式 .pkg 版 Node.js でグローバル領域が root 所有になっているのが典型です。

npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/@geekbeer
npm error errno -13

公式 pkg 版 Node.js を削除する

# 関連ファイルを削除
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

# pkg レシート削除
sudo rm -rf /var/db/receipts/org.nodejs.*

# ユーザー側のキャッシュ・設定
rm -rf ~/.npm ~/.node-gyp ~/.npmrc

その後 Homebrew 版を入れ直してください: brew install node

Step 1 で「User exists but has NO PASSWORD set」と表示される

過去に dscl 等でパスワードなしのユーザーを作った場合のメッセージです。auto-login と Screen Sharing にはパスワードが必須なので、設定してから setup を再実行してください。

sudo dscl . -passwd /Users/minion

Step 1 で「cannot prompt for password (non-interactive shell)」

非対話シェル（CI、ssh -t なし、バックグラウンド実行）から setup を起動した場合に出ます。ターミナルから直接実行するか、事前に手動でユーザーを作成してから setup を実行してください:

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

setup ログを残したい

tee はパイプ経由でバッファされ「フリーズしているように見える」ことがあるため、script を使うのが確実です。

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

詳細トレースが必要なら MINION_TRACE=1 を付けると全コマンドを stderr に出力します。

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

configure 時に「.env not found」エラー

setup と configure の実行ユーザーが違うときに起きます。configure は minion ユーザーで実行してください（admin ユーザーから直接ではなく）。

sudo su - minion          # ログインシェルで切り替え（PATH を再読み込み）
minion-cli-mac configure ...

`minion-cli-mac` コマンドが見つからない

minion ユーザーへ su した直後の PATH に Homebrew bin が入っていないケースです。setup の Step 6 で ~/.zprofile に brew shellenv を追記しているので、ログインシェル（su - の - あり）で切り替えると解決します。

sudo su - minion          # OK: -lc を経由するので .zprofile が読まれる
sudo su minion            # NG: 環境を引き継ぐので minion 側の PATH が反映されない

VNC が「黒画面」になる

ヘッドレス運用時に物理ディスプレイが接続されていません。HDMI ダミープラグを挿すか、ディスプレイを接続してください。

VNC が認証エラーで接続できない

~/.minion/.env の VNC_PASSWORD と macOS 側の VNC パスワードが食い違っています。setup を再実行するか、手動で再設定:

VNC_PW=$(awk -F'=' '/^VNC_PASSWORD=/{print $2}' ~/.minion/.env)
sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/Resources/kickstart \
  -configure -clientopts -setvnclegacy -vnclegacy yes -setvncpw -vncpw "$VNC_PW"

macOS Screen Sharing は VNC パスワードを 8 文字に切り詰めるため、vnc-auth-proxy も同じ切り詰めを行って整合させています。

LaunchAgent が起動しない

launchctl print gui/<UID> で対象ユーザーの GUI セッションが存在するか確認してください。LaunchAgent は GUI ログイン中のユーザーでしか動作しません。

# minion ユーザーの UID を確認
dscl . -read /Users/minion UniqueID

# GUI セッションが立ち上がっているか
launchctl print gui/<UID> | head -5

GUI セッションがない場合は、minion で物理ログインまたは Screen Sharing 経由でログインするか、auto-login を有効化してください。

FileVault が有効な可能性があります:

fdesetup status

FileVault is On. と出る場合、auto-login は macOS の仕様で無効です。FileVault を無効化するか、手動ログイン運用に切り替えてください。