Headscale self-host : le control plane Tailscale souverain (2026)

Divulgation d'affiliation - Cet article contient des liens d'affiliation Contabo. Si tu prends un VPS via ces liens, nous touchons une commission sans surcoût pour toi. Chaque commande et config ci-dessous est documentée à partir de sources officielles et écrite pour être reproductible sur ton propre VPS.

Si tu as lu notre comparatif Tailscale vs WireGuard self-host, tu sais déjà qu'Headscale est la troisième voie - celle qui combine l'UX de Tailscale et la souveraineté du self-host WireGuard. La question n'est plus "est-ce possible ?" mais "est-ce que ça vaut le coup d'investir le temps de setup ?". Ce guide y répond concrètement, sur la base d'un déploiement Headscale standard sur un VPS Contabo.

Au programme : ce qu'est vraiment Headscale, quand ça a du sens (et quand non), install pas-à-pas sur Contabo avec PostgreSQL et OIDC, configuration des ACLs, pièges en production que personne ne mentionne, et coûts réels sur 36 mois vs Tailscale Premium. À la fin tu pourras décider en 5 minutes si oui ou non tu investis les 2-3 jours nécessaires.

Ce qu'est réellement Headscale

Headscale est une réimplémentation open-source de l'API du coordinator Tailscale, écrite en Go, maintenue principalement par Juan Font et une communauté serrée de contributeurs. Code source : github.com/juanfont/headscale. Licence : BSD-3.

Ce n'est pas un fork de Tailscale. C'est un serveur qui parle le même protocole que le coordinator SaaS Tailscale - ce qui signifie que les clients officiels Tailscale (iOS, Android, macOS, Windows, Linux) peuvent pointer vers ton instance Headscale et se comporter normalement. Aucun client patché, aucun binaire custom douteux.

Ce que Headscale fait :

• Discovery et distribution de clés - exactement comme le coordinator SaaS.
• Coordination du NAT traversal - via les relais DERP (tu peux utiliser les relais DERP publics Tailscale gratuitement, ou self-host les tiens).
• ACLs déclaratives - accepte le même format JSON que Tailscale. Même syntaxe, même sémantique.
• MagicDNS - résolution des node.tailnet.example.com (ou le domaine que tu configures).
• Subnet routes - pour exposer un VPC ou un LAN derrière un nœud.
• Exit nodes - pour router tout le trafic internet via un nœud choisi.

Ce que Headscale ne fait pas (les limites honnêtes) :

• Pas de Premium features officielles : pas d'enregistrement de session SSH Tailscale, pas de console SSO native (tu branches l'OIDC toi-même), pas de GUI admin propriétaire (un projet headscale-ui séparé existe, tiers).
• La gestion des clients mobiles est plus manuelle - les auth keys doivent être générées en CLI.
• Le support Tailscale Inc. est inexistant - uniquement community support, GitHub Discussions et Discord.

La promesse est précise : l'essentiel de la valeur de Tailscale Premium, pour le prix d'un petit VPS, avec un control plane qui t'appartient.

Quand Headscale a vraiment du sens

Headscale n'est pas toujours la bonne réponse. Voici la matrice de décision pour trancher :

Les deux principales raisons pour lesquelles on déploie Headscale en production :

1. Souveraineté / compliance : le département légal ou la DSI interdit la dépendance SaaS non contrôlée. Headscale coche la case "hébergé en Europe, conforme GDPR, aucun transfert US". C'est le cas dans les SaaS B2B en EU qui grossissent.
2. Optimisation cash à l'échelle : à 15+ utilisateurs, Tailscale Premium devient des factures mensuelles à 4 chiffres. Un Contabo Cloud VPS 4 à 66 €/an + 2-3 jours de sysadmin coûte moins en cash ; le tableau sur 36 mois plus bas donne le calcul complet.

Si aucune de ces deux raisons ne s'applique à toi, reste sur Tailscale Premium ou WireGuard self-host raw. La voie médiane n'a de sens que si elle est vraiment justifiée.

Architecture retenue en production

Voici l'architecture de référence que ce guide suppose :

[Client Tailscale iOS/Android/Linux]
            │
            │ HTTPS (port 443)
            ▼
[Reverse proxy Caddy] ──► [Headscale]
            │                    │
            │                    ▼
            │            [PostgreSQL 15]
            │
            └──► [Tailscale DERP relays - public gratuit]

Composants :

• Contabo Cloud VPS 4 Nuremberg (4 vCPU, 8 Go RAM, 100 Go SSD, 5,50 €/mois) - voir notre avis Contabo 2026 et le tutoriel setup pas-à-pas pour préparer le VPS.
• Headscale 0.24 comme coordinator.
• PostgreSQL 15 comme backend (vs SQLite par défaut, plus robuste quand le nombre de nœuds augmente).
• Caddy 2 comme reverse proxy avec TLS automatique Let's Encrypt - Headscale nécessite HTTPS, les clients officiels l'exigent.
• OIDC via Authentik (aussi self-host, mais Auth0 ou Keycloak marchent tout aussi bien).
• Relais DERP publics Tailscale pour le NAT traversal - gratuits, pas besoin de self-host DERP sauf contrainte paranoïaque spécifique.

Install pas-à-pas sur Contabo

Durée setup sur VPS fraîchement provisionné : compter 90 minutes en suivant les étapes sans hésitation. On part sur Debian 12 (défaut Contabo).

1. Préparation système

apt update && apt upgrade -y
apt install -y postgresql postgresql-contrib caddy curl wget

2. Créer la base PostgreSQL Headscale

sudo -u postgres psql <<EOF
CREATE USER headscale WITH PASSWORD 'METS_UN_MOT_DE_PASSE_FORT_ICI';
CREATE DATABASE headscale OWNER headscale;
GRANT ALL PRIVILEGES ON DATABASE headscale TO headscale;
EOF

3. Installation Headscale

Le package.deb officiel est la voie la plus propre. Dernière release : github.com/juanfont/headscale/releases.

HS_VERSION="0.29.5"
wget https://github.com/juanfont/headscale/releases/download/v${HS_VERSION}/headscale_${HS_VERSION}_linux_amd64.deb
dpkg -i headscale_${HS_VERSION}_linux_amd64.deb

4. Configuration Headscale

Les valeurs ci-dessous valent pour Headscale 0.29 (octobre 2026). Pour obtenir le fichier complet adapté à ton installation (Docker ou .deb, Caddy, nginx ou TLS intégré, SQLite comme le recommande le projet), utilise notre générateur de config Headscale.

Édite /etc/headscale/config.yaml. Les paramètres minimum requis :

server_url: https://headscale.ton-domaine.com
listen_addr: 127.0.0.1:8080
metrics_listen_addr: 127.0.0.1:9090

database:
  type: postgres
  postgres:
    host: localhost
    port: 5432
    name: headscale
    user: headscale
    pass: METS_UN_MOT_DE_PASSE_FORT_ICI

derp:
  server:
    enabled: false
  urls:
    - https://controlplane.tailscale.com/derpmap/default

prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48

dns:
  magic_dns: true
  base_domain: ts.ton-domaine.com

policy:
  mode: file
  path: /etc/headscale/acl.json

oidc:
  issuer: https://auth.ton-domaine.com/application/o/headscale/
  client_id: headscale
  client_secret: OIDC_SECRET_ICI
  scope: ["openid", "profile", "email"]

Points critiques :

• server_url doit être en HTTPS. Les clients Tailscale officiels refusent le HTTP en clair.
• prefixes.v4 : 100.64.0.0/10 est la plage CGNAT utilisée par Tailscale par défaut. Ne change pas sauf si tu sais ce que tu fais.
• oidc : optionnel mais fortement recommandé en production. Sans OIDC, tu retombes sur headscale users create et des clés pré-partagées.

5. Caddy en reverse proxy

/etc/caddy/Caddyfile :

headscale.ton-domaine.com {
    reverse_proxy 127.0.0.1:8080
}

Reload : systemctl reload caddy. Caddy récupère automatiquement le certificat Let's Encrypt. Vérifie la chaîne avant d'aller plus loin - les clients officiels Tailscale refusent les certificats auto-signés.

6. Démarrer Headscale

systemctl enable --now headscale
journalctl -u headscale -f

Tu dois voir les logs de démarrage, puis "Listening on 127.0.0.1:8080".

7. Créer un premier utilisateur et une pre-auth key

headscale users create eric
headscale users list   # numeric ID of eric, e.g. 1
headscale preauthkeys create --user 1 --reusable --expiration 24h

La sortie te donne une clé tskey-auth-xxxxxxxxxxxx. Note-la.

8. Connecter un client Tailscale

Sur un client Linux avec le client Tailscale officiel installé :

tailscale up \
  --login-server https://headscale.ton-domaine.com \
  --authkey tskey-auth-xxxxxxxxxxxx

Le nœud apparaît dans headscale nodes list. À partir de là tu peux récupérer son IP 100.x.x.x et commencer à l'utiliser.

Pour iOS/Android : install l'app Tailscale officielle, settings → custom login server → ton URL Headscale. Tap "Sign in", tu seras redirigé vers ton provider OIDC.

Configuration des ACLs en mode production

Les ACLs c'est là où Headscale montre vraiment qu'il est "Tailscale-compatible". Le fichier JSON accepte la même syntaxe que les ACLs Tailscale Premium.

Exemple production (équipe 5 users avec ségrégation dev/staging) :

{
  "acls": [
    {
      "action": "accept",
      "src": ["group:admins"],
      "dst": ["*:*"]
    },
    {
      "action": "accept",
      "src": ["group:devs"],
      "dst": ["tag:dev:*", "tag:staging:22,80,443"]
    },
    {
      "action": "accept",
      "src": ["group:devs"],
      "dst": ["tag:prod:80,443"]
    }
  ],
  "groups": {
    "group:admins": ["eric@vpnsmith.com"],
    "group:devs": ["alice@vpnsmith.com", "bob@vpnsmith.com"]
  },
  "tagOwners": {
    "tag:dev": ["group:admins"],
    "tag:staging": ["group:admins"],
    "tag:prod": ["group:admins"]
  }
}

Reload après chaque modification : headscale acls reload. Headscale valide le JSON avant application, donc une erreur de syntaxe ne casse jamais le mesh prod.

Pièges en production que personne ne mentionne

Voici quatre pièges à anticiper quand on opère Headscale :

1. Saturation du pool de connexions PostgreSQL. Headscale plafonne ses connexions PostgreSQL (database.postgres.max_open_conns et max_idle_conns). Sur un mesh où beaucoup de nœuds se reconnectent souvent (typique du roaming Wi-Fi sur smartphone), un pool trop petit devient un goulot. Vérifie les valeurs par défaut dans la config d'exemple de ta version et augmente-les si les logs montrent des connexions en attente.

2. Les relais DERP publics Tailscale peuvent être loin de certains de tes nœuds. Quand le trafic est relayé par une région éloignée, la latence monte. Solution : self-host un relais DERP sur un VPS dans la région. Headscale s'en occupe de manière transparente - voir la doc DERP officielle.

3. Le backup PostgreSQL est obligatoire et sous-estimé. Headscale stocke tout dans PostgreSQL : nœuds, clés publiques, état des ACLs, mappings OIDC. Si tu perds la DB, tu perds le mesh entier. Mets en place pg_dump quotidien + backup automatique vers un stockage objet compatible S3 (par ex. Hetzner Object Storage, ~1 €/mois) et teste régulièrement ta restauration.

4. Les upgrades binaires Headscale sont gentils mais des breaking changes arrivent entre les versions mineures. Lis le CHANGELOG avant de passer de 0.23 à 0.24. L'équipe de dev est réactive sur GitHub mais Headscale est en développement actif - prévois-en à chaque upgrade.

Coûts réels sur 36 mois - Headscale vs Tailscale Premium

Le calcul à 10 utilisateurs, 25 nœuds, avec des hypothèses prudentes :

Headscale gagne ~2 230 € sur 36 mois à 10 users. Pas énorme, mais réel - et l'écart grandit linéairement avec la taille d'équipe. À 20 users on parle de ~8 000 € d'économies sur 3 ans. À 50 users c'est du sérieux.

Si ton temps vaut plus de 100 €/h, cet écart se rétrécit vite. S'il vaut moins de 50 €/h (junior, side project, apprentissage), Headscale gagne facilement.

Verdict - quand déployer Headscale en 2026

Déploie Headscale si :

• Tu as une contrainte de souveraineté / GDPR / aucun transfert US
• Ton équipe est à 10+ utilisateurs avec horizon 12+ mois
• Tu as un sysadmin en interne ou un réflexe sysadmin personnel
• Tailscale Premium te coûte cher mais WireGuard raw te semble trop primitif

Reste sur Tailscale Premium si :

• Ton temps vaut plus de 100 €/h
• Pas de contrainte de compliance spécifique
• Tu préfères consacrer ces 2-3 jours à ton produit

Reste sur WireGuard raw si :

• Tu es sous 5 nœuds, setup simple, mood apprentissage
• Hub-and-spoke répond à tous tes use cases

Headscale est la réponse la plus sous-estimée de l'écosystème self-hosted VPN en 2026. Il fait l'essentiel du travail de Tailscale, sur un VPS Contabo à 5,50 €/mois, avec souveraineté complète. Le prix : 2-3 jours de setup et un réflexe sysadmin.

Pour aller plus loin

• Headscale ou WireGuard : le tunnel et le serveur qui distribue les clés - ce que WireGuard seul vous laisse à faire, et ce que la documentation de Headscale dit qu'il n'est pas
• Tailscale vs WireGuard self-host : lequel choisir en 2026
• Self-host VPN sur Contabo : guide complet WireGuard 2026
• Setup VPS Contabo pas-à-pas pour VPN 2026
• Monitoring VPS VPN avec Prometheus + Grafana
• Avis Contabo 2026
• Calculateur de coût VPN auto-hébergé - entre ton nombre d'utilisateurs et ton TJM pour voir si Headscale, Tailscale ou WireGuard brut gagne sur le TCO
• Comparateur VPS interactif - compare Contabo, Hetzner et OVH par latence, RAM et prix réel 24 mois avant de choisir ton host Headscale

Sources et références :

• Headscale - code source et docs officielles
• Site de documentation Headscale
• Référence syntaxe ACL Tailscale
• Guide setup DERP server

Publié le 2026-06-05. Guide fondé sur la documentation officielle de Headscale, pas sur un déploiement de production à nous. Tarifs basés sur les pricing Contabo et Tailscale de mai 2026 - à vérifier avant décision. Performances et économies réelles dépendent de la taille d'équipe et de l'infrastructure existante.

Rappel : Headscale, Tailscale et le self-hosting VPN sont parfaitement légaux dans l'UE, aux US, au Canada. VPNSmith publie ce contenu à des fins éducatives.