Skip to content

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.

Setup uses Homebrew and stops right at the start if it is missing, so install it first:

Terminal window
/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.

Install it with Homebrew:

Terminal window
brew install node

Run setup from a user with administrator rights.

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:

Terminal window
sudo pmset -a sleep 0 # never put the Mac to sleep
sudo pmset -a autorestart 1 # start up after a power failure (on Macs that support it)

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)”
Terminal window
npm install -g @geekbeer/minion

If 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.

Terminal window
sudo minion-cli-mac setup --user minion

If 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 minion user
  • 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 minion user 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:

Terminal window
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).

Switch to the minion user and run the second half of the commands HQ showed you (configure):

Terminal window
sudo su - minion
minion-cli-mac configure \
--hq-url https://<your HQ URL> \
--minion-id <minion ID> \
--api-token <API token> \
--setup-tunnel

Keep --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.

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.

The minion shows as online on the Minions page. You can also check on the Mac (as the minion user):

Terminal window
minion-cli-mac status # the minion's status
minion-cli-mac health # health check

Run these as the minion user:

Terminal window
minion-cli-mac status # the minion's status
minion-cli-mac health # health check
minion-cli-mac daemons # state of the work running inside the minion (watching the board and so on)
minion-cli-mac diagnose # detailed diagnosis
minion-cli-mac restart # restart the minion
minion-cli-mac stop # stop the minion
minion-cli-mac start # start the minion
minion-cli-mac --version # version

restart, stop and start act on the minion itself only. The screen sharing relay and the connection to HQ (cloudflared) keep running.

Terminal window
tail -f ~/.minion/logs/agent.out.log
tail -f ~/.minion/logs/agent.err.log
tail -f ~/.minion/logs/vnc-proxy.out.log # screen sharing relay
tail -f ~/.minion/logs/cloudflared.err.log # connection to HQ

When the minion’s page in HQ shows Update to v…, press it to update.

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.

Run these as the administrator user. Type yes when asked to confirm.

Terminal window
sudo minion-cli-mac uninstall --user minion # --keep-data keeps the minion's data (~/.minion)
npm uninstall -g @geekbeer/minion

These stay behind; undo them by hand if you no longer need them:

  • The minion user (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 minion user’s ~/.zprofile

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.

npm install -g fails with EACCES: permission denied

Section titled “npm install -g fails with EACCES: permission denied”
npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/@geekbeer
npm error errno -13

You are using Node.js from the official installer (.pkg). Remove it and install it again with Homebrew.

Terminal window
# The program
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
# The installer's records
sudo rm -rf /var/db/receipts/org.nodejs.*
# Your cache and settings
rm -rf ~/.npm ~/.node-gyp ~/.npmrc

Then 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:

Terminal window
sudo dscl . -passwd /Users/minion

Setup 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:

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

configure was run by a user other than minion. Switch with sudo su - minion and run it again.

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).

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:

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"

The connection to HQ (Cloudflare Tunnel) is set up only when configure runs with --setup-tunnel. Find the cause as the minion user:

Terminal window
# 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
SymptomWhat to do
There is no config.ymlRun 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 serviceThe 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 runs only while the minion user is logged in to the screen. Check that it is:

Terminal window
# Find the minion user's UID
dscl . -read /Users/minion UniqueID
# Is that UID logged in?
launchctl print gui/<UID> | head -5

If not, log in as minion directly on the Mac or through screen sharing, or turn on automatic login.

FileVault may be on:

Terminal window
fdesetup status

If it says FileVault is On., macOS doesn’t allow automatic login. Turn FileVault off, or log in by hand after each restart.

tee can buffer output so setup looks frozen; use script instead:

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

For more detail, MINION_TRACE=1 prints every command setup runs:

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