# juanfont/headscale

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/juanfont-headscale).**

35,565 stars · 1,905 forks · Go · bsd-3-clause

## Links

- GitHub: https://github.com/juanfont/headscale
- awesome-repositories: https://awesome-repositories.com/repository/juanfont-headscale.md

## Topics

`tailscale` `tailscale-control-server` `tailscale-server` `wireguard`

## Description

Headscale is a self-hosted control plane for private mesh networking that enables the creation of secure, encrypted peer-to-peer networks. By acting as a centralized coordination server, it manages device authentication, cryptographic key exchange, and network topology, allowing distributed infrastructure to communicate without relying on third-party services. It implements a zero-trust security architecture, verifying device and user identity before granting access to internal resources.

The project distinguishes itself by providing a fully independent, self-hosted alternative for managing network overlays. It integrates with external identity providers to automate user authentication and enforces granular, declarative access control policies across a fleet of devices. Administrators can manage the network through a web-based dashboard, a REST API, or a gRPC interface, providing flexibility for both manual oversight and programmatic automation.

The system supports a wide range of networking capabilities, including remote subnet routing, exit node configuration, and automated DNS management. It ensures connectivity across diverse environments through relay-based NAT traversal, which facilitates communication even when direct peer-to-peer connections are blocked by firewalls. The platform also maintains state persistence using a relational database and automates security through integrated TLS certificate management.

The software is available as a standalone binary or via containerized deployment, with support for cross-platform clients across various mobile and desktop operating systems.

## Tags

### Networking & Communication

- [Control Plane Protocols](https://awesome-repositories.com/f/networking-communication/control-plane-protocols.md) — Uses a centralized server to exchange cryptographic keys and network topology information between peers.
- [Mesh Networking](https://awesome-repositories.com/f/networking-communication/mesh-networking.md) — Builds secure, encrypted peer-to-peer networks that connect devices across different locations without requiring complex firewall or router configuration.
- [NAT Traversal Mechanisms](https://awesome-repositories.com/f/networking-communication/nat-traversal-mechanisms.md) — Employs intermediary servers to facilitate connection handshakes and relay traffic when direct communication is blocked.
- [Mesh Network Coordinators](https://awesome-repositories.com/f/networking-communication/mesh-network-coordinators.md) — Provides a self-hosted control server that manages device authentication, key exchange, and network topology for secure peer-to-peer private networks.
- [Subnet Routing](https://awesome-repositories.com/f/networking-communication/subnet-routing.md) — Connects isolated private networks or cloud environments by routing traffic through authorized gateway nodes within a unified virtual network.
- [VPN Controllers](https://awesome-repositories.com/f/networking-communication/vpn-controllers.md) — Orchestrates encrypted tunnels between distributed nodes to create a unified and private network overlay.
- [Cross-Platform Clients](https://awesome-repositories.com/f/networking-communication/cross-platform-clients.md) — Links diverse mobile and desktop operating systems to a private mesh network. ([source](https://headscale.net/stable/usage/connect/android/))
- [Exit Node Routing](https://awesome-repositories.com/f/networking-communication/exit-node-routing.md) — Designates specific nodes as internet gateways to allow other network participants to route their web traffic through these secure exit points. ([source](https://headscale.net/stable/ref/routes/))
- [gRPC Administrative Interfaces](https://awesome-repositories.com/f/networking-communication/grpc-administrative-interfaces.md) — Executes administrative tasks on server instances through a secure gRPC interface. ([source](https://headscale.net/stable/ref/api/))
- [REST Administrative APIs](https://awesome-repositories.com/f/networking-communication/rest-administrative-apis.md) — Performs administrative operations like user management and node registration via authenticated HTTP requests. ([source](https://headscale.net/stable/ref/api/))
- [Subnet Traffic Routing](https://awesome-repositories.com/f/networking-communication/subnet-traffic-routing.md) — Advertises specific local network segments and approves those routes on the central controller to enable communication between private networks. ([source](https://headscale.net/stable/ref/routes/))
- [DNS Management](https://awesome-repositories.com/f/networking-communication/dns-management.md) — Automates the creation and maintenance of static or dynamic internal naming records to improve service discovery across the entire network. ([source](https://headscale.net/stable/ref/dns/))
- [High Availability Routing](https://awesome-repositories.com/f/networking-communication/high-availability-routing.md) — Deploys multiple routing nodes with overlapping configurations to provide redundant paths for traffic and maintain connectivity during unexpected network outages. ([source](https://headscale.net/stable/ref/routes/))

### Security & Cryptography

- [Identity-Aware Infrastructure](https://awesome-repositories.com/f/security-cryptography/identity-aware-infrastructure.md) — Integrates corporate identity providers to automate user authentication and enforce access policies across a distributed fleet of devices.
- [Zero Trust Access Controls](https://awesome-repositories.com/f/security-cryptography/zero-trust-access-controls.md) — Manages granular network permissions by verifying every device and user identity before granting access to specific internal resources.
- [Declarative Access Control](https://awesome-repositories.com/f/security-cryptography/declarative-access-control.md) — Enforces network-wide security policies by parsing structured configuration files defining communication permissions.
- [Software-Defined Perimeters](https://awesome-repositories.com/f/security-cryptography/software-defined-perimeters.md) — Restricts network access by verifying device identity and enforcing granular communication policies before allowing connection.
- [Access Control Policies](https://awesome-repositories.com/f/security-cryptography/access-control-policies.md) — Enforces network-wide security policies through declarative configuration files to control traffic flow. ([source](https://headscale.net/stable/ref/acls/))
- [Identity-Aware Proxies](https://awesome-repositories.com/f/security-cryptography/identity-aware-proxies.md) — Acts as a gateway service that integrates with external authentication providers to manage secure access to private resources based on user identity.
- [OIDC Identity Integrations](https://awesome-repositories.com/f/security-cryptography/oidc-identity-integrations.md) — Delegates user authentication to external identity providers to map secure tokens to internal network access policies.
- [Node Registration](https://awesome-repositories.com/f/security-cryptography/node-registration.md) — Onboards new network devices using pre-generated authentication keys or interactive approval flows. ([source](https://headscale.net/stable/ref/registration/))
- [Dynamic Access Groups](https://awesome-repositories.com/f/security-cryptography/dynamic-access-groups.md) — Organizes devices into dynamic collections that automatically update access rules based on membership status. ([source](https://headscale.net/stable/ref/acls/))
- [TLS Certificate Management](https://awesome-repositories.com/f/security-cryptography/tls-certificate-management.md) — Manages security certificates through automated ACME domain validation or manual configuration, with built-in monitoring to ensure timely renewals. ([source](https://headscale.net/stable/ref/tls/))

### DevOps & Infrastructure

- [Network Coordination Planes](https://awesome-repositories.com/f/devops-infrastructure/network-coordination-planes.md) — Provides a private control plane to manage device authentication, routing, and connectivity for distributed infrastructure without relying on third-party services.
- [Coordination Server Deployments](https://awesome-repositories.com/f/devops-infrastructure/coordination-server-deployments.md) — Hosts the control plane on public-facing infrastructure to manage client connectivity and provide centralized oversight. ([source](https://headscale.net/stable/setup/requirements/))
- [Containerized Deployments](https://awesome-repositories.com/f/devops-infrastructure/containerized-deployments.md) — Runs services within isolated container environments by mounting configuration volumes and exposing necessary network ports. ([source](https://headscale.net/stable/setup/install/container/))

### User Interface & Experience

- [Administrative Dashboards](https://awesome-repositories.com/f/user-interface-experience/administrative-dashboards.md) — Provides a graphical web interface to monitor device health and adjust configuration settings. ([source](https://headscale.net/stable/ref/integration/web-ui/))

### Data & Databases

- [Relational Database Persistence](https://awesome-repositories.com/f/data-databases/relational-database-persistence.md) — Stores network topology, node metadata, and authentication state in a structured database.