Setting up a macOS minion (previous version)
Install @geekbeer/minion on a Mac (mini, Studio, MacBook and so on) and that Mac can work as a minion (self-hosted). The minion runs as a dedicated minion user. You need administrator rights (sudo) only for the initial setup and for uninstalling; day-to-day operation works from the minion user.
What you need
Section titled “What you need”Homebrew
Section titled “Homebrew”Setup uses Homebrew and stops right at the start if it is missing, so install it first:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Afterwards, follow the instructions it prints to add brew shellenv to ~/.zprofile, or open a new terminal window.
Node.js 22 or later
Section titled “Node.js 22 or later”Install it with Homebrew:
brew install nodeAn administrator user
Section titled “An administrator user”Run setup from a user with administrator rights.
FileVault and automatic login
Section titled “FileVault and automatic login”The minion runs only while the minion user is logged in. To keep it running after the Mac restarts, the minion user has to log in automatically — but macOS doesn’t allow automatic login while FileVault is on. Choose what suits you:
- To run it around the clock — turn FileVault off and turn on automatic login for
minion - If logging in by hand after each restart is fine — you can keep FileVault on
Sleep and power failures (when running around the clock)
Section titled “Sleep and power failures (when running around the clock)”Setup stops only the display from sleeping, not the Mac itself. To run around the clock, keep the Mac from sleeping and have it start up again after a power failure:
sudo pmset -a sleep 0 # never put the Mac to sleepsudo pmset -a autorestart 1 # start up after a power failure (on Macs that support it)1. Register the minion in HQ
Section titled “1. Register the minion in HQ”Open Minions in the sidebar, click Add Minion, choose Self-host VPS and press Register Minion. (Its description mentions Ubuntu/Debian, but it is also the option for a Mac.)
HQ then shows the commands to run. Choose macOS and copy them — the Linux commands don’t work on a Mac. You can find the same commands later under Setup Command on the minion’s page.
2. Install the package (administrator user)
Section titled “2. Install the package (administrator user)”npm install -g @geekbeer/minionIf you get EACCES: permission denied, Node.js came from the official installer. Switch to Homebrew’s Node.js as described in Node.js 22 or later.
3. Run setup (administrator user)
Section titled “3. Run setup (administrator user)”sudo minion-cli-mac setup --user minionIf the minion user doesn’t exist yet, setup asks for a password and creates it. Automatic login and screen sharing both need a password, so it can’t be empty.
Setup then does the following (it takes a few minutes):
- Creates the
minionuser - Installs what it needs with Homebrew (tmux, ttyd, jq, node, cloudflared)
- Installs Claude Code and the Gemini CLI
- Turns on screen sharing and sets its VNC password. The password is generated for you and stays on this Mac
- Stops asking for a password after sleep or the screensaver, and keeps the display from sleeping
- Registers the minion to start when the
minionuser logs in
4. Turn on screen sharing in System Settings
Section titled “4. Turn on screen sharing in System Settings”On macOS Ventura and later, setup alone can’t turn screen sharing on. Turn on System Settings → General → Sharing → Screen Sharing.
To check that it’s on, run the following. A LISTEN line means it’s on:
netstat -an -p tcp | grep '\.5900 'lsof -iTCP:5900 can’t tell you: the screen sharing process runs with administrator rights, so without sudo it shows nothing even when sharing is on.
5. Turn on automatic login (when running around the clock)
Section titled “5. Turn on automatic login (when running around the clock)”In System Settings → Users & Groups → Automatically log in as, choose minion. The option doesn’t appear while FileVault is on (see FileVault and automatic login).
6. Connect to HQ (the minion user)
Section titled “6. Connect to HQ (the minion user)”Switch to the minion user and run the second half of the commands HQ showed you (configure):
sudo su - minion
minion-cli-mac configure \ --hq-url https://<your HQ URL> \ --minion-id <minion ID> \ --api-token <API token> \ --setup-tunnelKeep --setup-tunnel. HQ reaches the minion through this tunnel; without it, the terminal, screen and files won’t work from HQ. The commands HQ shows include it.
Always switch with - (sudo su - minion). Without it, the minion user’s PATH isn’t loaded and minion-cli-mac isn’t found.
7. Sign in to the AI
Section titled “7. Sign in to the AI”A minion needs an AI model (LLM) it can use before it can do any work. From the minion’s page in HQ, open screen sharing (VNC) to the Mac as the minion user, run claude in Terminal and sign in. To use a different AI, see LLM Plugins.
8. Check that it works
Section titled “8. Check that it works”The minion shows as online on the Minions page. You can also check on the Mac (as the minion user):
minion-cli-mac status # the minion's statusminion-cli-mac health # health checkDay-to-day commands
Section titled “Day-to-day commands”Run these as the minion user:
minion-cli-mac status # the minion's statusminion-cli-mac health # health checkminion-cli-mac daemons # state of the work running inside the minion (watching the board and so on)minion-cli-mac diagnose # detailed diagnosisminion-cli-mac restart # restart the minionminion-cli-mac stop # stop the minionminion-cli-mac start # start the minionminion-cli-mac --version # versionrestart, stop and start act on the minion itself only. The screen sharing relay and the connection to HQ (cloudflared) keep running.
tail -f ~/.minion/logs/agent.out.logtail -f ~/.minion/logs/agent.err.logtail -f ~/.minion/logs/vnc-proxy.out.log # screen sharing relaytail -f ~/.minion/logs/cloudflared.err.log # connection to HQUpdating
Section titled “Updating”When the minion’s page in HQ shows Update to v…, press it to update.
Reconnecting
Section titled “Reconnecting”If you recreate the connection details with Re-register in HQ, run configure again with the command it shows. If that command has no --setup-tunnel, add it.
Running setup again never removes the existing connection details, so when something is missing or broken you can run it again to repair it.
Uninstalling
Section titled “Uninstalling”Run these as the administrator user. Type yes when asked to confirm.
sudo minion-cli-mac uninstall --user minion # --keep-data keeps the minion's data (~/.minion)npm uninstall -g @geekbeer/minionThese stay behind; undo them by hand if you no longer need them:
- The
minionuser (remove it in System Settings → Users & Groups) - What was installed with Homebrew
- Screen sharing (still on) and the sleep, screensaver and display settings
- The lines added to the
minionuser’s~/.zprofile
Running without a display
Section titled “Running without a display”When a Mac mini runs without a display, screen sharing has no screen to show, and HQ’s screen sharing goes black.
Plug an HDMI dummy plug (headless display adapter) into the HDMI port. macOS then sees a display, and screen sharing works. They are inexpensive, and nothing needs to be configured. If the shared screen looks shrunk or enlarged, change the resolution in System Settings → Displays.
Troubleshooting
Section titled “Troubleshooting”npm install -g fails with EACCES: permission denied
Section titled “npm install -g fails with EACCES: permission denied”npm error code EACCESnpm error syscall mkdirnpm error path /usr/local/lib/node_modules/@geekbeernpm error errno -13You are using Node.js from the official installer (.pkg). Remove it and install it again with Homebrew.
Removing the official .pkg Node.js
Section titled “Removing the official .pkg Node.js”# The programsudo 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
# The installer's recordssudo rm -rf /var/db/receipts/org.nodejs.*
# Your cache and settingsrm -rf ~/.npm ~/.node-gyp ~/.npmrcThen install it again with brew install node.
Setup says “User exists but has NO PASSWORD set”
Section titled “Setup says “User exists but has NO PASSWORD set””The minion user has no password. Automatic login and screen sharing need one, so set it and run setup again:
sudo dscl . -passwd /Users/minionSetup says “cannot prompt for password (non-interactive shell)”
Section titled “Setup says “cannot prompt for password (non-interactive shell)””Setup was started somewhere it can’t ask for a password (a script, the background and so on). Run it directly in Terminal, or create the user first and then run setup:
sudo sysadminctl -addUser minion -fullName "Minion Agent" -password "YOUR_PASSWORD"sudo minion-cli-mac setup --user minionconfigure says “.env not found”
Section titled “configure says “.env not found””configure was run by a user other than minion. Switch with sudo su - minion and run it again.
minion-cli-mac is not found
Section titled “minion-cli-mac is not found”You switched to the minion user without -. With sudo su - minion, the minion user’s settings (~/.zprofile) are loaded and the command is found.
HQ’s terminal says claude: command not found
Section titled “HQ’s terminal says claude: command not found”This happens on Macs set up with a version older than 5.10.0. Update the minion, run sudo minion-cli-mac setup --user minion again, and open a new terminal in HQ (terminals already open keep the old settings).
Screen sharing is black
Section titled “Screen sharing is black”No display is connected. Plug in an HDMI dummy plug or a display (see Running without a display).
Screen sharing fails with an authentication error
Section titled “Screen sharing fails with an authentication error”The VNC password the minion saved and macOS’s screen sharing password don’t match. Run setup again, or run the following as the administrator user to set them to the same value:
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 shows TUNNEL as FAIL
Section titled “diagnose shows TUNNEL as FAIL”The connection to HQ (Cloudflare Tunnel) is set up only when configure runs with --setup-tunnel. Find the cause as the minion user:
# 1. Is it set up?head -3 ~/.cloudflared/config.yml
# 2. Is it running?launchctl print gui/$(id -u)/com.geekbeer.cloudflared | grep state
# 3. Why did it stop?tail -30 ~/.minion/logs/cloudflared.err.log| Symptom | What to do |
|---|---|
There is no config.yml | Run configure again with --setup-tunnel |
credentials-file points to /etc/cloudflared/... | The minion was set up with an older version. Update it and run configure again |
Could not find service | The minion user isn’t logged in to the screen. Turn on automatic login, log in as minion, then try again (it can’t start from a shell opened with ssh or su -) |
The minion doesn’t start
Section titled “The minion doesn’t start”The minion runs only while the minion user is logged in to the screen. Check that it is:
# Find the minion user's UIDdscl . -read /Users/minion UniqueID
# Is that UID logged in?launchctl print gui/<UID> | head -5If not, log in as minion directly on the Mac or through screen sharing, or turn on automatic login.
Automatic login doesn’t work
Section titled “Automatic login doesn’t work”FileVault may be on:
fdesetup statusIf it says FileVault is On., macOS doesn’t allow automatic login. Turn FileVault off, or log in by hand after each restart.
Recording setup for a support request
Section titled “Recording setup for a support request”tee can buffer output so setup looks frozen; use script instead:
script -q /tmp/minion-setup.log sudo minion-cli-mac setup --user minionFor more detail, MINION_TRACE=1 prints every command setup runs:
sudo MINION_TRACE=1 minion-cli-mac setup --user minion 2> /tmp/minion-trace.log