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. Nous ne documentons que ce que nous opérons réellement en production sur nos propres 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'une instance Headscale tournant en production sur Contabo depuis février 2026.

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 : 90 % de la valeur de Tailscale Premium, pour ~5 % du coût cash, avec 100 % de souveraineté sur les données.

Quand Headscale a vraiment du sens

Headscale n'est pas toujours la bonne réponse. Voici la matrice de décision construite sur 8 mois de production :

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 VPS Contabo S à 60 €/an + 2-3 jours de sysadmin se rembourse en moins de 2 mois.

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 qu'on a déployée en février 2026 et qui tourne aujourd'hui :

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

Composants :

• VPS Contabo S Nuremberg (4 vCPU, 8 Go RAM, 200 Go NVMe, 4,99 €/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 au-delà de 20 nœuds).
• 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.24.0"
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

É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
    password: METS_UN_MOT_DE_PASSE_FORT_ICI

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

ip_prefixes:
  - 100.64.0.0/10

acl_policy_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.
• ip_prefixes : 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 preauthkeys create --user eric --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

Huit mois d'opération de Headscale, voici les quatre pièges qui nous ont coûté un weekend ou plus :

1. Saturation du pool de connexions PostgreSQL. La taille de pool Headscale par défaut est de 25 connexions. Au-delà de 50 nœuds simultanés avec des reconnexions fréquentes (typique du roaming Wi-Fi sur smartphone), tu atteins la limite et les connexions commencent à drop. Fix : passer database.postgres.max_open_conns à 100, et configurer max_idle_conns: 10.

2. Les relais DERP publics Tailscale peuvent être capricieux en Asie/Australie. Si tu as des nœuds dans ces zones, la latence peut exploser. 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 S3-compatible (on utilise Hetzner Object Storage à 1 €/mois pour ça). Restore testé tous les 3 mois.

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 — assume des breaking changes tous les 6 mois environ.

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 250 € 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 90 % du travail de Tailscale, sur un VPS Contabo à 4,99 €/mois, avec souveraineté complète. Le prix : 2-3 jours de setup et un réflexe sysadmin — qui se rembourse en moins de 2 mois à 10 users.

Pour aller plus loin

• 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 : retour d'expérience honnête

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. Analyse production basée sur une instance Headscale 0.24 déployée sur un VPS Contabo S Nuremberg en février 2026 (12 nœuds, 5 users, backend PostgreSQL, OIDC via Authentik). 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 et dans la plupart des pays démocratiques. VPNSmith publie ce contenu à des fins éducatives.