Engineering problem

Self-Hosted Tailscale Control with Headscale

Pilot a Headscale control server with Linux, Android or iOS, and test enrollment, access policy, traffic relays and backup before migrating your tailnet.

Editorial update

Decision in brief

Choose Headscale when you need to operate coordination yourself, a single tailnet suffices, and you can own TLS, upgrades and recovery. Keep the managed Tailscale control plane if a required client or workflow fails the pilot, or if there is no clear operator for the new control server.

Choose coordination: Headscale — Own the server. Managed Tailscale — Reduce upkeep. Either choice — Test clients.
Check feature fit and assign ownership of upgrades, TLS and restoration before switching.

Start with the control plane and check each client

Headscale implements an alternative control server for Tailscale clients. Enroll clients against your own server URL and check features by client version. Put your pilot on a dedicated hostname with valid HTTPS reachable by the devices that need to enroll or reconnect. Test Android through the app's alternate server flow and follow the Apple-specific setup guide for iOS or macOS.

Decide how peers will connect when they cannot establish a direct path. Headscale documents optional embedded DERP and the use of external relay maps. Hosting coordination changes who operates registration and policies. A requirement to run your own relays needs a separate test of the relay configuration and availability.

RequirementPilot designDecision evidence
Laptop and mobile clientsOne Linux peer and one actual iOS or Android deviceEnroll each on the custom server, reach a private test service and verify reconnection.
Identity and revocationPersonal test accounts or the intended OIDC providerRemove a disposable device and confirm that its access ends as expected.
Independent relay operationDocument the selected DERP map and keep fallback access during the pilotCheck the reported connection path and usability from the two networks the devices normally use.
Work devices with required managed featuresList each required workflow and verify on the exact device versionKeep the current network for any workflow the test cannot reproduce.

Two HN accounts to add to your checklist

fidelramos posted a walkthrough covering both Headscale and its clients. Treat client configuration as a separate deliverable. Record the app version and the onboarding path for every operating system your users will bring.

hwdsl2 described packaging a Headscale instance that generates configuration and a pre-auth key on first run. An installer can shorten the first connection. Your continuing responsibilities include expiring enrollment credentials, refreshing TLS and restoring service state.

Stage two peers before moving a real device

  1. Install a pinned release on a disposable host. Document the test hostname, registration method, chosen relay policy, configuration and data paths. Keep the existing network available.
  2. Enroll two owned devices, connect to a harmless test service from an approved peer and verify that a test identity outside the allowed group cannot reach it. Repeat after changing the mobile device from Wi-Fi to cellular.
  3. Revoke one disposable peer. Recover the instance from backups in a separate environment, then repeat registration and the policy check on that restore.
  4. Proceed if all required clients enroll, the allowed and denied checks pass, and recovery fits your target. Try 60 minutes for a small pilot. Stop if an essential device needs an unsupported feature or a revoked peer retains access.

Related articles