Self-Hosted Headscale on a Small Cloud VM
smoores.neocities.org
Step-by-step guide: install Headscale 0.29 behind nginx on a small cloud VM, back it up, and connect Linux, Windows, macOS, iOS, Android, Synology, JetKVM and TinyPilot devices. Accessible version with light, dark, low-light and e-ink viewing modes.

AI Disclosure:

  • Implementation - Hint. Syntax was reviewed and polished by AI.
  • Testing - Assisted. AI was used to troubleshoot whenever I got stuck
  • Documentation - Generated

I spent the last three months slowly tinkering with Headscale and trying to get it to run on one of Google’s “free-tier” cloud instances, while also learning about GCI’s strange setup. During that time I used Claude Sonnet to keep track of my progress and help me troubleshoot whenever I got stuck. I finally got it going and before I closed the project, I asked Claude to document my work along with all pertinent information and create and admin cheatsheet, just in case I forget. I liked the output, so I asked the LLM to sanitize my data and recreate my project as a step-by-step walktrhough in a single HTML page.

PROVIDED AS-IS!!! Do not copy and paste code blindly. Use this as a walkthough/guide and NOT as a recipe book. You WILL need to correct code.

EDIT: It looks like for this document, Claude also took it upon itself to further clean my configs, scripts, etc., and add a lot of comments to make it all easier to understand. I DO NOT work this cleanly. It looks correct though.

  • CaptainShardmind@lemmy.worldEnglish
    1·
    33 minutes ago

    Nice to see this written up end to end. I stuck with Tailscale’s hosted coordination server, but I do run my reverse proxy on a free-tier cloud VM, and the lesson carries over: treat the VM as disposable and keep what you’d need to rebuild it somewhere else. For Headscale that means backing up the database and the server’s private keys, because if the VM disappears and you start fresh, every node has to re-register. It’s also worth reading the provider’s free-tier terms before leaning on it as your only way into the network.