Canonical page: https://koalavps.com/guides-self-host-headscale-on-a-vps/ Language: English. Source snapshot: 2026-10-21. Generated: 2026-10-21T13:31:28.274Z. [Home](https://koalavps.com/) / [Explore](https://koalavps.com/resources/) / The KoalaVPS field notes The KoalaVPS field notes # A control plane for a private mesh. Headscale can coordinate a compatible private network. Keep the control-plane, relay and access-policy roles distinct. [Find your VPS](https://koalavps.com/vps/) ## IN THIS DOCUMENT [Understand what is coordinated](https://koalavps.com/guides-self-host-headscale-on-a-vps/#section-1)[Make enrollment intentional](https://koalavps.com/guides-self-host-headscale-on-a-vps/#section-2)[Review ACLs and routes](https://koalavps.com/guides-self-host-headscale-on-a-vps/#section-3)[Keep the recovery material](https://koalavps.com/guides-self-host-headscale-on-a-vps/#section-4)[Registration, routing and policy are separate checks](https://koalavps.com/guides-self-host-headscale-on-a-vps/#section-5)[Do not put the only recovery path inside the mesh](https://koalavps.com/guides-self-host-headscale-on-a-vps/#section-6)[Fix the control-plane identity and recovery route](https://koalavps.com/guides-self-host-headscale-on-a-vps/#section-7)[Enroll one device before advertising a network](https://koalavps.com/guides-self-host-headscale-on-a-vps/#section-8)[Approve routing and authorisation independently](https://koalavps.com/guides-self-host-headscale-on-a-vps/#section-9)[Find the broken layer before changing the policy](https://koalavps.com/guides-self-host-headscale-on-a-vps/#section-10)[Knowledge base](https://koalavps.com/resources/) ## Understand what is coordinated The control plane manages node registration and distributes network information. Data traffic may use direct peer connections or a relay depending on connectivity. Running the coordinator does not mean every packet passes through it. ## Make enrollment intentional Protect the administrative API and use short-lived or appropriately scoped registration methods. Remove devices that are lost or retired. The ability to join the mesh should not imply access to every service. ## Review ACLs and routes Apply least-privilege rules between users and nodes. Advertised subnet routes and exit nodes expand the reachable network and need explicit approval. Test denied traffic as carefully as permitted traffic. ## Keep the recovery material Back up configuration, state and keys according to the supported version’s procedure. Keep a way to administer the VPS if the mesh fails. Verify client compatibility and upgrade notes before changing the control plane. ## Registration, routing and policy are separate checks Headscale coordinates compatible Tailscale clients; direct connections and DERP relay paths have different network behaviour. A subnet router advertises a range, the control server approves it, and the client must accept the route. Enable forwarding on the routing node and keep advertised ranges narrow. An approved route still needs an access policy limiting who may use which destination and port. - Check the control server’s route list - Test from an allowed device - Repeat the same test from a device that should be denied ``` headscale nodes list-routes ``` Official documentation: [Headscale routes](https://headscale.net/stable/ref/routes/) ## Do not put the only recovery path inside the mesh Keep a second way to reach the server console or a tightly restricted administrator route. Test what happens when the coordinator, relay or client is unavailable. Preserve control-plane state and keys according to the installed version. A private mesh can simplify access, but it should not become an undocumented dependency that prevents its own repair. ## Fix the control-plane identity and recovery route Choose a stable HTTPS name, a supported Headscale release and compatible Tailscale clients. Read the configuration example shipped with that exact release; a configuration copied from a different release can fail validation or silently describe a different policy. Persist the control-plane database and required keys. Keep the administrative API private and retain a separate console or restricted SSH route, so losing the mesh does not make its coordinator impossible to repair. - Use a certificate valid for the public control-plane name. - Keep enrollment keys short lived and appropriately scoped. - Treat the relay design and DNS namespace as explicit choices. Official documentation: [Headscale container deployment](https://headscale.net/stable/setup/install/container/) ## Enroll one device before advertising a network Bring up the server using upstream instructions and register one test user/device through the documented enrollment method. Confirm the device reaches the expected control URL and appears under the intended identity. Inspect client status and test one private service before adding exit-node or subnet routes. A DERP path can preserve connectivity where a direct path is unavailable; it does not indicate that the coordinator is forwarding every packet. - Start with a device and service you can remove safely. - Check whether peer traffic is direct or relayed. - Protect the relay and control endpoints according to the selected deployment. Official documentation: [Headscale deployment reference](https://headscale.net/stable/setup/install/container/) ## Approve routing and authorisation independently For subnet access, enable forwarding on the routing node, advertise a narrow range, approve it on the control server and make sure the destination client accepts it. Avoid overlapping networks that make the return route ambiguous. An approved route is not an access policy: define who can connect to which destination and port, including guest devices. Test an allowed connection and an identical denied connection before extending the mesh. ``` # Run on the control server; syntax follows the installed release: headscale nodes list-routes # Client-side inspection: tailscale status ``` Official documentation: [Headscale subnet and exit routes](https://headscale.net/stable/ref/routes/) ## Find the broken layer before changing the policy If enrollment fails, inspect DNS, HTTPS and the server URL. If the device joins but a subnet is unreachable, inspect advertisement, approval, client route acceptance, forwarding and the return path. If only one service fails, inspect its bind address, host firewall and mesh policy. Preserve a consistent database/configuration backup and test a version upgrade with a disposable client before changing the only control plane. KEEP EXPLORING ## Continue reading. [Guides ### A private tunnel with a clear purpose. WireGuard can connect your devices to a server or private network. Its benefits depend on correct routing, DNS and endpoint securi…](https://koalavps.com/guides-wireguard-vpn-on-a-vps/)[Use cases ### A home for your private applications. Run the dashboards, APIs and internal tools that help your project work, with access designed around the people who need it.…](https://koalavps.com/private-apps/)[Guides ### A backup matters when it restores. Design a backup around the data you cannot recreate and the time your service can afford to lose. A successful upload is only the …](https://koalavps.com/backups/) CONFIGURE YOUR INFRASTRUCTURE ## Take control. Deploy on your terms. No identity paperwork. Full administrator access. Crypto-native billing. [Select a configuration](https://koalavps.com/vps/)