---
title: Headscale
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, vpn, mesh, tailscale, zerotrust, nat-traversal, go, wireguard, coordination-server]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=VPN, https://github.com/juanfont/headscale]
---

# 🔐 Headscale

> **L'implémentation open source du serveur de coordination Tailscale** — auto-hébergez votre mesh VPN WireGuard sans dépendre du cloud de Tailscale Inc.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | [headscale.net](https://headscale.net/) |
| **GitHub** | [juanfont/headscale](https://github.com/juanfont/headscale) |
| **License** | Apache-2.0 |
| **Langage** | Go |
| **Étoiles GitHub** | 39 729 ⭐ |
| **Dernière MAJ** | 2026-06-07 |
| **Catégorie** | [[cat-vpn|VPN & Réseau privé]] |

## 📝 Description

**Headscale** est un **serveur de coordination open source** compatible avec le client officiel Tailscale. Là où Tailscale propose un service managé (control plane + coordination), Headscale réimplémente la partie serveur en Go pour vous permettre de garder le contrôle total sur l'infrastructure de votre mesh VPN. Concrètement, vos machines (serveurs, laptops, téléphones) exécutent le **client Tailscale officiel** et se connectent à votre instance Headscale au lieu du serveur de Tailscale Inc.

C'est l'une des pierres angulaires du mouvement "**self-sovereign networking**" : vous obtenez la simplicité d'usage de Tailscale (NAT traversal magique, MagicDNS, ACLs, partage de nœuds entre utilisateurs) sans confier vos métadonnées réseau à un tiers. Le projet, démarré en 2021 par Juan Font, est désormais largement utilisé en production par des homelabbers, des associations et même des entreprises.

- ✅ **100% compatible avec le client Tailscale officiel** (CLI, GUI macOS/Windows/Linux/iOS/Android)
- ✅ **NAT traversal** : Hole punching STUN + relais DERP (vous pouvez aussi héberger vos propres DERP)
- ✅ **MagicDNS** : résolution automatique des noms de pairs
- ✅ **ACLs** (JSON) et **Tailnet Lock** (vérification des clés)
- ✅ **Multi-tenants** (plusieurs "users"/namespaces)
- ✅ **PreAuth keys** : enrollement simplifié (QR code, clé à usage unique)
- ✅ **Exit nodes** : partager une connexion internet via le mesh
- ✅ **Subnets** : router des sous-réseaux entiers à travers un pair
- ✅ **OpenID Connect / OIDC** : intégration SSO (Keycloak, Authentik, Google…)
- ✅ **Binaire Go unique** ou image Docker officielle
- ✅ **API REST + CLI `headscale`**

**Public cible** : homelabbers avancés, équipes infra qui refusent le SaaS Tailscale, organisations avec contraintes de souveraineté (santé, finance, administration). Pour un usage basique solo, **Tailscale gratuit (100 devices, 3 users)** est souvent plus simple — Headscale prend tout son sens quand on veut échapper à la dépendance au cloud ou quand on dépasse les limites gratuites.

**Vs Tailscale SaaS** : Headscale offre les mêmes protocoles (WireGuard + Noise + DERP), mais l'écosystème de fonctionnalités Tailscale (Taildrop, SSH Tailscale, Funnel public) peut être en retard de quelques versions. Le client reste exactement le même.

## 🚀 Installation

### Option 1 : Docker Compose (recommandé)

```yaml
# docker-compose.yml
version: '3.8'
services:
  headscale:
    image: headscale/headscale:latest
    container_name: headscale
    restart: unless-stopped
    command: serve
    ports:
      - "443:443"      # API HTTPS
      - "80:80"        # Let's Encrypt challenge
      - "51820:51820/udp"  # WireGuard (optionnel en mode userspace)
    volumes:
      - ./config:/etc/headscale
      - ./data:/var/lib/headscale
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.headscale.rule=Host(`headscale.example.com`)"
      - "traefik.http.routers.headscale.entrypoints=websecure"
      - "traefik.http.routers.headscale.tls.certresolver=letsencrypt"
      - "traefik.http.services.headscale.loadbalancer.server.port=443"

  derp:
    image: ghcr.io/tailscale/derper:latest
    container_name: derper
    restart: unless-stopped
    command: /derper --hostname=derp.example.com --verify-clients=false
    ports:
      - "51820:51820/udp"  # Réutilisation du port WireGuard pour STUN
      - "443:443"          # Relay HTTPS
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.derp.rule=Host(`derp.example.com`)"
      - "traefik.http.routers.derp.tls.certresolver=letsencrypt"
```

> 💡 Le serveur **DERP** (relais) ci-dessus est optionnel mais recommandé : il améliore drastiquement le NAT traversal et la latence en cas de hole-punching impossible.

### Option 2 : Binaire natif (Debian/Ubuntu)

```bash
curl -fsSL https://github.com/juanfont/headscale/releases/latest/download/headscale_linux_amd64 -o /usr/local/bin/headscale
chmod +x /usr/local/bin/headscale
# Générer la config
headscale generate private-key
sudo mkdir -p /etc/headscale
curl -fsSL https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -o /etc/headscale/config.yaml
# Systemd unit
sudo systemctl enable --now headscale
```

## ⚙️ Configuration Initiale

1. **Créer un namespace utilisateur** : `headscale users create velli`
2. **Générer une PreAuth Key** : `headscale preauthkeys create -u velli -e 24h --reusable --tags=tag:server`
3. **Enregistrer un client** sur la machine cliente :
   ```bash
   tailscale up --login-server https://headscale.example.com --authkey=<PREAUTH_KEY>
   ```
4. **(Optionnel) Activer MagicDNS** dans `config.yaml` (`magic_dns: enabled: true`)
5. **(Optionnel) Configurer les ACLs** dans `/etc/headscale/acl.yaml` puis recharger
6. **Vérifier** : `headscale nodes list` doit lister le pair nouvellement enregistré

## 🔄 Alternatives

### Open Source
- [[app-tailscale]] (SaaS officiel — gratuit jusqu'à 100 devices)
- [[app-netbird]] — Concurrent direct, panel web intégré, plus jeune
- [[app-zerotier]] + [[app-ztnet]] — Mesh global, philosophie différente (L2 Ethernet-like)
- [[app-wg-easy]] — WireGuard "classique" site-à-site, sans mesh
- **Innernet** — WireGuard mesh par tonic (sponsor Tailscale)

### Propriétaires
- **Tailscale** (freemium : 100 devices / 3 users, puis 5$/user/mois)
- **Cloudflare Tunnel** (zero-trust + WARP, gratuit avec limits)
- **Zscaler Private Access** (entreprise)
- **Palo Alto Prisma Access**

### Comparaison Headscale vs alternatives

| Critère | Headscale | Tailscale SaaS | NetBird | ZeroTier |
| :--- | :--- | :--- | :--- | :--- |
| Self-hosted control plane | ✅ | ❌ | ✅ | ❌ (ZTnet = partiel) |
| License | Apache-2.0 | Propriétaire | Apache-2.0 | BSL (gros clients) |
| Protocol base | WireGuard | WireGuard | WireGuard | Propre (L2) |
| NAT traversal | STUN + DERP | STUN + DERP (rapide) | STUN + ICE | Propre |
| OIDC/SSO | ✅ | ✅ | ✅ | ❌ |
| ACLs | ✅ (avancées) | ✅ (très fines) | ✅ | Basiques |
| MagicDNS | ✅ | ✅ | ✅ | ❌ |
| UI web | ❌ (CLI only) | ✅ | ✅ | ❌ |

**Verdict** : si vous aimez Tailscale mais voulez **maîtriser vos métadonnées** réseau, Headscale est aujourd'hui le choix le plus mature. NetBird est son challenger le plus crédible grâce à son panel web.

## 🔐 Sécurité

- ✅ **WireGuard** : cryptographie moderne (Curve25519 pour l'échange de clés, ChaCha20-Poly1305 pour le chiffrement, BLAKE2s pour le hachage) — l'IP publique des pairs peut fuiter via le serveur de coordination (utiliser **Tailnet Lock** pour mitiger)
- ✅ **Clés privées WireGuard** : générées localement sur chaque machine, **JAMAIS transmises** au serveur de coordination (qui n'est qu'un "annuaire" — il ne voit pas le trafic)
- ✅ **OIDC** : connecter Headscale à [[app-authentik]] ou Keycloak pour SSO + **MFA obligatoire** sur l'admin
- ✅ **ACLs strictes** : principe du moindre privilège dans `acl.yaml`, auditer régulièrement
- ✅ **Logs d'audit** : Headscale logge tous les enregistrements/départs de pairs, exporter vers [[app-loki]] ou Wazuh
- ⚠️ Sauvegarder la **clé privée du serveur** (`private_key.pem`) et la **clé Noise** dans [[app-vaultwarden]] ou un coffre-fort — leur perte = perte du contrôle du tailnet
- ⚠️ Activer **Tailnet Lock** en production pour empêcher un attaquant d'enregistrer un faux pair

## 📚 Ressources

- [Site officiel Headscale](https://headscale.net/)
- [GitHub juanfont/headscale](https://github.com/juanfont/headscale)
- [Documentation](https://headscale.net/kb/)
- [Comparatif Headscale vs Tailscale](https://headscale.net/comparison/)

## Pages Liées
- [[cat-vpn]] — Catégorie VPN & Réseau privé
- [[app-tailscale]] — Le client officiel utilisé avec Headscale
- [[app-netbird]] — Concurrent open source
- [[app-wireguard]] — Le protocole sous-jacent
- [[app-traefik]] — Reverse proxy / HTTPS
- [[app-authentik]] — SSO OIDC
- [[securisation-home-lab]] — Bonnes pratiques globales
- [[glossaire-homelab]] — Définitions réseau
- [[comparatif-vpn-mesh]] — Comparatif global mesh VPN