agentleFS
soulmachinesoulmachine/skills/mac-mini-as-headless-server/SKILL.md

mac-mini-as-headless-server

Skill3 starsChanged yesterdayMITView on GitHub

Use when setting up a Mac (especially Mac Mini or Apple Silicon Mac Studio) for unattended 24/7 server operation, headless use, or remote-only access. Covers sleep prevention, screen saver, Wake-on-LAN, auto-restart, App Nap, SSH enablement, and — on Apple Silicon — a caffeinate LaunchDaemon that stops the headless display from parking (physical panel and VNC/screen-share going black even with displaysleep=0). Targets macOS 15 (Sequoia) and later.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run the bundled script as root, via sudo from the target user's account (it refuses to run from a bare root shell so per-user defaults land …

    line 42

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Configure macOS for Server Use

Overview

Configures macOS for unattended 24/7 server operation by disabling sleep, screen saver, and App Nap, while enabling Wake-on-LAN, auto-restart after power failure, and SSH remote login. The screen lock lives in the user keybag and changing it requires the user's account password (root alone can't), so the script verifies it, offers to turn it off when run interactively (you type the user's password once), and prints the exact CLI/GUI fix on unattended runs.

Requires sudo. Targets macOS 15 (Sequoia) and later. Target hardware: Mac Mini, Mac Studio, or any Mac used as a headless server.

Apple Silicon caveat: on an Apple Silicon Mac with no local keyboard/mouse, pmset displaysleep 0 is not enough. WindowServer still parks the physical display (DPMS off ~30s after each wake), which turns the panel black and makes RealVNC / screen-capture sessions show black, because they capture the physical display. The only reliable fix is to hold a PreventUserIdleDisplaySleep assertion continuously — this skill installs a caffeinate -d LaunchDaemon (step 7) for that.

When to Use

  • Setting up a Mac as a home server, CI runner, or always-on machine
  • Preparing a Mac Mini for headless/remote-only operation
  • Troubleshooting a Mac that keeps sleeping, locking, or becoming unreachable
  • Fixing a headless Apple Silicon Mac whose physical display or VNC/screen-share session goes black despite displaysleep 0

Quick Reference

SettingCommandEffect
Screen saver offdefaults -currentHost write com.apple.screensaver idleTime -int 0Disables screen saver activation
System sleep offpmset -c sleep 0Never sleep
Display sleep offpmset -c displaysleep 0Never turn off display
Disk sleep offpmset -c disksleep 0Never spin down disks
Dim before sleep offpmset -c halfdim 0No pre-sleep dimming (absent/no-op on some modern Macs — not listed in their pmset -g custom)
Wake-on-LANpmset -c womp 1Wake on network access
Auto-restartpmset -c autorestart 1Restart after power loss
App Nap offdefaults write NSGlobalDomain NSAppSleepDisabled -bool YESPrevents app throttling
SSH onsystemsetup -setremotelogin onEnables Remote Login — needs Full Disk Access; confirm with -getremotelogin
Keep display awake (Apple Silicon)caffeinate -d via LaunchDaemonHolds PreventUserIdleDisplaySleep — stops the headless display park that displaysleep 0 does not prevent (panel + VNC go black)
Screen lock statussysadminctl -screenLock statusReports lock state — no sudo needed
Screen lock offsysadminctl -screenLock off -password -Needs the user's account password (user keybag) — root/sudo alone can't change it. Scriptable form: -password 'pw'. Step 8 runs the interactive form for you on TTY runs

Implementation

Run the bundled script as root, via sudo from the target user's account (it refuses to run from a bare root shell so per-user defaults land in the right account):

sudo bash scripts/setup.sh

What it does, in order:

  1. Screen saver off — idleTime 0, per-user
  2. All sleep off — pmset -c sleep/displaysleep/disksleep/halfdim 0
  3. Wake-on-LAN — womp 1
  4. Auto-restart after power failure — autorestart 1
  5. App Nap off — per-user global default
  6. SSH on — systemsetup -setremotelogin on; needs Full Disk Access and can fail while exiting 0, so trust the verify output, not this step
  7. Keep-display-awake LaunchDaemon — writes /Library/LaunchDaemons/com.local.keepdisplayawake.plist running caffeinate -d (RunAtLoad + KeepAlive, survives reboots), loads it, then fires caffeinate -u -t 2 to wake an already-parked panel. Follows with a verification dump: pmset -g, daemon state (want a PID), display assertion (want caffeinate listed), and systemsetup -getremotelogin (want On)
  8. Screen lock — checks sysadminctl -screenLock status (no sudo needed). On an interactive (TTY) run it prompts once for the user's account password and turns the lock off in place; unattended runs get the manual GUI/CLI instructions instead

Common Mistakes

  • Running without sudo — pmset and systemsetup require root; defaults commands must run as the real user via sudo -u
  • Omitting the power-source flag — pmset defines -a (all), -b (battery), -c (charger), -u (UPS); the man page doesn't say which profile a flagless write targets, so be explicit — -c (or -a) on a desktop
  • Expecting immediate effect — Screen saver and lock-screen changes may require logout/restart
  • FileVault blocking auto-login — Auto-login (System Settings > Users & Groups > Login Options) requires FileVault off
  • Trusting systemsetup -setremotelogin on — it requires Full Disk Access (per man systemsetup) and historically exits 0 even on failure, so a plain run can silently do nothing. Always confirm with systemsetup -getremotelogin (the script prints it in the verify block)
  • Relying on pmset displaysleep 0 alone on Apple Silicon — it does not stop the headless display park; you need the caffeinate -d LaunchDaemon (step 7). Symptom: the physical panel and/or VNC session is black even though pmset -g shows displaysleep 0.
  • Expecting caffeinate -d to wake a black screen — -d only prevents sleep; it won't wake an already-parked panel. Fire a one-shot caffeinate -u -t 2 to wake it (step 7 does this after loading the daemon).
  • Running a bare caffeinate -d instead of the LaunchDaemon — an orphaned/nohup'd caffeinate holds the assertion until the next reboot, then silently dies and the display parks again. Use the LaunchDaemon (step 7) so it comes back at boot.
  • Trying to disable the screen lock with defaults write com.apple.screensaver askForPassword -int 0 — ignored since macOS 10.13 High Sierra, though old blog posts still recommend it. The setting lives in the user keybag (MobileKeyBag) and changing it needs the user's account password — root/sudo alone can't do it, but it is scriptable if you supply the password: sysadminctl -screenLock off -password 'pw' (or -password - to be prompted). Verify with sysadminctl -screenLock status — no sudo needed (step 8). For fleets, an MDM configuration profile with the com.apple.screensaver payload is the hands-off alternative.

Reverting

To restore display sleep later:

sudo pmset -c displaysleep 10  # 10 minutes

To remove the keep-display-awake LaunchDaemon (step 7):

sudo launchctl bootout system /Library/LaunchDaemons/com.local.keepdisplayawake.plist
sudo rm /Library/LaunchDaemons/com.local.keepdisplayawake.plist

To re-enable the screen lock (as the user, no sudo; prompts for the account password):

sysadminctl -screenLock immediate -password -   # or a delay in seconds

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.