Headless Mac Mini for AI Agents: VNC, SSH, and launchd

• Use Screen Sharing or VNC when the agent needs a real desktop.
• Use SSH for logs, installs, recovery, and launchd control.
• Prevent automatic sleep and enable network wake where supported.
• Use launchd to restart agent processes after login or boot.
• Use Mac mini auto login only when a GUI session must recover unattended, and understand the FileVault tradeoff.
• Keep VNC off the public internet. Prefer VPN, private network, or SSH tunnel.
• Use Hyperbox when you want the always-on Mac runtime without owning the physical and network recovery story.

A headless Mac mini for agents is not just a Mac with no monitor. It is a dedicated Mac server with a user session, desktop permissions, shell access, process supervision, logs, credentials, and a recovery path.

• Create a dedicated standard macOS user for agent work.
• Keep a separate admin account for maintenance.
• Set a stable hostname such as `agent-mini.local`.
• Prefer Ethernet for a 24/7 machine.
• Decide how you will reach the Mac: LAN, VPN, private network, or SSH tunnel.
• Install Xcode Command Line Tools, package managers, browser dependencies, and agent runtimes before you remove the monitor.
• Confirm you have a recovery path if SSH, Screen Sharing, or launchd breaks.

For a desktop Mac, configure Energy settings so the computer does not automatically sleep when the display is off. Apple notes that available sleep and wake controls vary by Mac. The point is simple: if the Mac sleeps, your agent host is not actually 24/7.

sudo systemsetup -setsleep Off
sudo systemsetup -setwakeonnetworkaccess on
sudo systemsetup -setrestartfreeze on
sudo systemsetup -setrestartpowerfailure on
sudo systemsetup -setWaitForStartupAfterPowerFailure 30
pmset -g
pmset -g assertions

Use caffeinate for a single long-running command. Do not use it as a substitute for correct sleep settings and service recovery.

caffeinate -is ./run-agent-workload.sh

Use SSH for the boring work: logs, package installs, Git, launchd, and recovery. Use Screen Sharing or VNC when the agent or human needs to see a desktop, browser, simulator, permission dialog, or app window.

sudo systemsetup -setremotelogin on
ssh agentuser@agent-mini.local

open "vnc://agent-mini.local"

# Safer VNC path over SSH:
ssh -N -L 5901:127.0.0.1:5900 agentuser@agent-mini.local
open "vnc://127.0.0.1:5901"

Mac mini auto login is tempting for GUI agents because a reboot can return directly to the user desktop where LaunchAgents, browser profiles, menu bar apps, and Accessibility-approved automation live. It is also a security tradeoff.

Use a LaunchAgent for GUI agents and browser automation because they need the logged-in user's desktop permissions. Use a LaunchDaemon only for system services that do not require a GUI session.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>sh.hyperbox.agent-runner</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/agent/bin/run-agent.sh</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/Users/agent/workspace</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/Users/agent/Library/Logs/agent-runner.out.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/agent/Library/Logs/agent-runner.err.log</string>
</dict>
</plist>

mkdir -p ~/Library/LaunchAgents ~/Library/Logs
plutil -lint ~/Library/LaunchAgents/sh.hyperbox.agent-runner.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/sh.hyperbox.agent-runner.plist
launchctl kickstart -k "gui/$(id -u)/sh.hyperbox.agent-runner"
launchctl print "gui/$(id -u)/sh.hyperbox.agent-runner"

A DIY headless Mac mini is a good answer if you like owning the whole stack: hardware, power, network, physical recovery, OS updates, remote access, backups, and security boundaries. Hyperbox is the better answer when the Mac should be an agent runtime instead of another machine you maintain.

Can a Mac mini run headless without a monitor?

Yes. For agent hosting, the key pieces are remote access, sleep prevention, a reliable service manager, and a way to recover after reboot or network interruption.

Should I enable Mac mini auto login on an agent Mac?

Only when the workload truly needs an interactive desktop after reboot, and never for an administrator account unless you accept the physical-access risk. Prefer least-privilege users.

Do I need Screen Sharing or SSH?

Use both when possible: SSH for logs and service control, Screen Sharing or VNC for GUI tasks, browser work, and Computer Use workflows.