How to run coding agents on a Mac mini nobody touches

A Mac mini is a good box to leave running coding agents on. It is small, quiet and always plugged in. But macOS ships tuned for a person sitting in front of it, not for a machine nobody touches for weeks, and the setting that stops you is not the one you would guess.

The one rule: never let the screen lock

Sleep is not the main problem. The lock is. macOS cannot launch a new graphical application while the screen is locked. Apps that are already open keep working, and background processes carry on, but anything new that needs the display fails at startup.

So on a locked Mac, a graphical agent host cannot start. In DevThrottle that application is the Director, which means no scheduled run, no remote request and no restart after an update until a person unlocks the machine. There is no setting or launch trick around this. The fix is the one every commercial Mac build farm uses: the display may turn off, but the session never locks.

The price of that, stated plainly

After this setup the machine logs itself in at boot, never locks, and its disk is not encrypted. Anyone with physical access owns it and everything on it. That is the right trade for a Mac in a locked home or office only you can touch. It is the wrong trade for a laptop or a shared space.

The settings that matter

• Turn FileVault off. Automatic login does not exist while it is on, because the encrypted disk needs a typed password before macOS can start: sudo fdesetup disable.
• Turn on automatic login, so every restart lands on a logged-in desktop: sudo sysadminctl -autologin set -userName <user> -password -.
• Stop the display from locking the session. This is the setting that prevents the lock: sysadminctl -screenLock off -password -. The old defaults write trick stopped working around macOS 13.
• Keep the machine awake, and let the display sleep. sudo pmset -a sleep 0 keeps it up, and sudo pmset -a displaysleep 10 is harmless once the lock is off. sudo pmset -a autorestart 1 starts it again after a power failure. Some Apple Silicon minis honour that one inconsistently, so test yours by pulling the plug.
• Stop full OS updates installing themselves. They reboot the machine and end every running session. Keep security updates automatic, and install macOS updates yourself in a window you choose.
• Keep a way in. sudo systemsetup -setremotelogin on gives you ssh over your private network for the day the graphical session cannot be reached. Keep Screen Sharing as the second door.

Privacy permissions are the one part no script can do. Full Disk Access and Screen Recording need a person clicking in System Settings, once. A grant is inherited by every process the granted app launches, so granting the Director covers the agents it starts.

Prove it before you walk away

• Restart it. It must reach the desktop with nobody touching it.
• Turn the display off with pmset displaysleepnow, wait a minute, and start a new agent session remotely. It must launch cleanly.
• Pull the power for ten seconds. It should boot itself back to the desktop.
• From another machine, check that ssh and Screen Sharing both connect.

If the mini has no monitor, buy an HDMI dummy plug. It is the cheapest fix for the rendering and screenshot oddities a monitor-less Mac produces.

The complete checklist, with the System Settings path for each step and the extra update and quiet-machine commands, is on Running a Mac unattended. The script scripts/mac-unattended-setup.sh in the open source repository shows the current value of every setting and asks before each change.