Turning a Mac Mini Into an Always-On Claude Code Server

A Mac mini is an unusually good fit for an always-on agent box. Apple Silicon idles at a few watts, the fanless or near-silent models are easy to leave running on a shelf, and unlike a Linux VPS it gives you a full macOS environment, which matters if any of your work touches Xcode, iOS builds, or other macOS-only tooling. None of that happens automatically out of the box, though: a fresh Mac mini is configured to behave like a laptop that goes to sleep, not a server that stays up. This guide covers the handful of settings that change that, plus the trade-offs worth knowing before you commit to it.

Power settings: stay awake without a display

The single most common failure mode for a first attempt at a headless Mac is that the machine looks reachable but has actually gone to sleep. In System Settings, under Energy (Battery on some configurations), turn off automatic sleep for the system, and separately enable "Wake for network access" so the box responds to an incoming SSH connection instead of staying asleep through it. The display can still sleep independently of the system; that is fine and saves power, since you are not looking at it anyway.

Also enable "Start up automatically after a power failure," in the same Energy settings, so a brief outage does not leave the Mac sitting powered off until someone physically presses the button. If the box is somewhere with unreliable power, a small UPS is worth it for the same reason: it turns a power blip into a non-event instead of a multi-hour gap.

Auto-login vs. FileVault: pick one trade-off deliberately

This is the setting people get wrong most often, because the two options interact in a way that is not obvious until a reboot leaves the box unreachable. It is worth being precise about what actually happens:

• SSH does not need a logged-in user. The Remote Login (SSH) service on macOS runs as a system daemon that starts independently of any user session, so a fresh reboot with nobody logged in is still reachable over SSH, auto-login or not.
• FileVault is the real gate. If FileVault full-disk encryption is enabled, the disk is not decrypted until someone enters the FileVault password at a pre-boot screen, before macOS itself, SSH, or Screen Sharing have even started. Auto-login only skips the macOS user login that happens after that unlock; it cannot skip the pre-boot step.

In practice that means a headless Mac mini with FileVault turned on will sit inert after any full restart (a power failure, a macOS update that requires a reboot) until someone is physically present to type the FileVault password. There is no remote workaround for a single unmanaged Mac outside of enterprise device-management tooling. The honest choices are: accept that trade-off and plan reboots around physical access, or leave FileVault off and rely on other controls (a locked room, full-disk backups, restricting physical access to the box) for data at rest.

Session supervision: launchd, not just tmux

tmux or screen solves connection persistence: your Claude Code session keeps running when your SSH connection drops. It does not solve crash recovery: if the process itself dies, tmux just shows you an empty pane. launchd is the macOS-native answer to that second problem. A LaunchAgent (runs in a user's session) or a LaunchDaemon (runs system-wide, before any user logs in) with a KeepAlive key in its property list restarts the process automatically if it exits unexpectedly, and can also start it fresh on boot.

The two tools do different jobs and are meant to be combined: launchd keeps the process itself alive and supervised, and tmux (or a similar multiplexer) gives you a stable place to reattach and interact with it. Neither one, on its own, gives you the other's job.

Network reachability without a static IP

Most home and small-office internet connections hand out a dynamic IP address that can change without warning, which breaks a hardcoded SSH target. Two common fixes: a dynamic DNS service republishes your current public IP under a stable hostname whenever it changes, or a mesh VPN such as Tailscale or WireGuard assigns the box a private address that stays constant regardless of your ISP, reachable from any device also on that mesh without forwarding a port on your router. The VPN route is generally the safer of the two, since it never exposes SSH directly to the public internet.

Security basics for a box that is on all the time

• Key-only SSH. Set PasswordAuthentication no in /etc/ssh/sshd_config and authenticate with a key pair instead.
• A dedicated, non-admin account. Run the agent under its own user account rather than your everyday admin account, and scope its permissions to what it actually needs.
• The built-in firewall. In System Settings, under Network, turn on the firewall and allow only the services you actually use.
• Prefer a VPN over an open port, as covered above, so SSH is never reachable from the open internet at all.
• Physical security. A headless Mac mini is still a physical box; anyone who can plug a keyboard into it has more access than anyone on the network does.
• Stay current. Security updates matter more, not less, on a machine that is reachable around the clock.

Where this fits with the rest of your setup

Getting the Mac mini itself right (awake, reachable, supervised, and secured) is the foundation. What you actually do with that always-on box, whether that is SSH and tmux, VS Code Remote-SSH, or steering it from your phone, is covered in our broader guide to running Claude Code remotely. If the phone angle specifically is what you are after, including push notifications when a long run finishes, see Claude Code on your phone.

Frequently asked questions