Skip to content

Setting up a macOS minion

Install Minion on a Mac and the Mac works as your minion. Minion runs as a background service, connects out to Minion Workspace (you don’t open any port) and updates itself.

  • A Mac with Apple silicon, macOS 13 or later
  • An administrator account — for installing Minion and for setting the minion account’s password
  • A Minion Workspace account
  1. Download the installer (.pkg) from Download Minion.
  2. Double-click it, follow the installer and enter an administrator password.

The installer creates a macOS user for the minion (user name minion), starts Minion Agent as a service, gives screen sharing a password only Minion Agent knows, and puts Minion in the Applications folder.

Open Minion from the Applications folder. It shows Minion Agent’s state, a code and a link. Open the link while signed in to Minion Workspace (or open minionworkspace.com/pair and type the code).

The page shows the Mac’s name, OS and the address it connected from. Check that it is your Mac, give the minion a name, choose the workspace it belongs to (one where you are the owner or an admin) and click Approve. The code is valid for 10 minutes; if it expires, Minion shows a new one. The minion appears on the Minions page and connects within a few seconds.

macOS doesn’t let an installer turn screen sharing on. Turn on System Settings → General → Sharing → Screen Sharing yourself.

The minion’s AI works as the macOS user minion, and only while that user is logged in. Until then, the minion’s page says Sign in to the minion account.

  1. Set the password (first time only). In Terminal, run this command. Type your administrator password, then the minion account’s password twice (12 characters or more):

    Terminal window
    sudo /usr/local/minion/bin/minion configure-worker
  2. Log in as minion. Choose Log Out from the Apple menu (or switch users from Control Center), then log in as the minion (user name minion) with that password.

You can switch to another user afterwards: the minion keeps working while minion stays logged in.

On the minion’s page in Minion Workspace, open the Brain tab, install Claude Code, then choose what the minion uses: Minion AI, your own Anthropic API key (how), or your own Claude plan (sign in from the tab; it opens the minion’s terminal in Minion Workspace).

On the minion’s page:

  • the minion is online
  • the Terminal opens a shell as minion
  • Screen sharing shows the Mac’s screen

Then send it a message from the chat.

Minion updates itself: it checks for a new version every few hours and installs it when the minion isn’t working. To update right away, use Update to version … now on the minion’s page, or run sudo /usr/local/minion/bin/minion update --now. minion update shows the updater’s state.

WhatHow
Is Minion running and connected?Open Minion from the Applications folder, or run minion status in Terminal
RestartRestart Agent on the minion’s page
After a restart of the MacLog in as minion again (unlock FileVault first if it is on)
Keep the Mac awakeSystem Settings: keep the Mac from sleeping automatically, and don’t require a password after the screen saver begins

Run this command in Terminal. The data Minion kept on the Mac (the minion account included) is removed too, and screen sharing’s settings go back to what they were before:

Terminal window
sudo /usr/local/minion/bin/minion uninstall

Then delete the minion on the Minions page if you no longer need it.

If you install Minion again on the same Mac, you can connect it back to the same minion. What Minion Workspace keeps (its name, its workspace and project memberships, tickets assigned to it and so on) carries on. The data on the Mac itself (memories, routines, to-dos and so on) was removed when you uninstalled.

  1. In Minion Workspace, open the minion’s Overview tab and click Reset pairing
  2. Install Minion again. On the approval page, under How to connect, choose Reattach to an existing minion and pick the minion

Screen sharing shows what the Mac’s screen shows. On a Mac mini without a monitor, it can be black or very small: plug an HDMI dummy adapter into the Mac so macOS sees a display.

The installation fails on a Mac that has the previous minion

Section titled “The installation fails on a Mac that has the previous minion”

The previous minion (the Node.js version) keeps running as it was. See Switching to the new Minion → Troubleshooting for the common causes.

The minion’s page says “Sign in to the minion account”

Section titled “The minion’s page says “Sign in to the minion account””

The minion user isn’t logged in. Follow step 4. After a restart, log in again.

Screen sharing doesn’t connect or is black

Section titled “Screen sharing doesn’t connect or is black”

Check that System Settings → General → Sharing → Screen Sharing is on (step 3). With no monitor, use an HDMI dummy adapter.

Open Minion from the Applications folder, or run minion status in Terminal. If it shows waiting for approval with a code and a link, open the link and approve.