Headscale & Tailscale – MacOS Installation
Here’s how to install Tailscale with a Headscale server on macOS. First, download and install the Tailscale application found on Tailscale Web site.
Additionally, I wrote this blog post in French. After open the application, in the menu bar, click on the Tailscale icon while holding down the “option” key, then click on the “Debug” and “Add Account” menus to specify your alternative (Headscale) server.
Add the url of your Headscale server and click on “Add Account”.
A window of your browser will open with the information to create the Headscale account.
Retrieve the value of mkey, then open a terminal on the Headscale machine and execute this command:
docker exec headscale headscale nodes register --user USERNAME---key mkey:xxxxxxxxxxxxxxxxxxxxxxxx To do this via the HeadPlane interface, on the “Machinery” page, click “Add Device”, add the character string mkey:xxx, choose the user and click “Register”.
I invite you to read or return to the Headscale and Tailscale post.
One Comment
Leave a Reply
Stabilizing Headscale on macOS: The CLI “Sleep” Fix
Intro & Credits First off, a massive thank you to Lucas for your blog posts that inspired this setup. It was the perfect starting point for getting my private mesh network running with Headscale.
My Setup & The Problem I chose a headless route: running a self-hosted Headscale controller on a VPS and using the Tailscale CLI (Terminal version) on my MacBook—no GUI app.
While the initial connection worked, I hit a persistent wall: The “Sleep Death.” Every time I closed my MacBook lid or changed Wi-Fi networks, the connection dropped and wouldn’t recover automatically. Trying to reconnect manually (tailscale up) would often hang indefinitely without providing an authentication URL, likely due to a mismatch between the client expecting HTTPS and my server using HTTP.
Restarting the Mac has worked, but very annoying…
The Diagnosis We realized that the standard CLI installation on macOS runs as a user process. When macOS goes to sleep, it freezes these user processes. Upon waking up, the network driver is lost, and the process doesn’t have the permissions or the “state” to restart the tunnel automatically. We also found that the interactive browser login was failing silently in the background.
The Solution The fix required moving Tailscale from a “user program” to a “system service” (Daemon) and bypassing the browser login entirely.
1. Clean Up: Killed any zombie processes from previous attempts. sudo pkill tailscaled
2. Run as Root Daemon: Instead of running it manually, I used Homebrew to register it as a system launch daemon. This ensures macOS manages the lifecycle and restarts it after sleep. sudo brew services start tailscale
3. The “Pre-Auth” Bypass: To avoid the HTTP/HTTPS browser hang, I generated a Pre-Auth Key on my Headscale server (using the User ID, not the name, to avoid syntax errors).
4. The Magic Command: I authenticated using sudo (essential to talk to the root daemon) and the key: sudo tailscale up –login-server http://:8080 –authkey –accept-dns=false –reset –force-reauth
The Test The ultimate validation:
Connected successfully.
Closed the MacBook lid (Sleep mode).
Waited 2 minutes.
Opened the lid and immediately pinged my NAS.
Result: Instant response. No hanging, no manual restarts. The mesh is finally stable.