Headscale self-host: el control plane Tailscale soberano (2026)

Divulgación de afiliación — Este artículo contiene enlaces de afiliación de Contabo. Si compras un VPS a través de estos enlaces, recibimos una comisión sin coste adicional para ti. Solo documentamos lo que realmente operamos en producción en nuestros propios VPS.

Si has leído nuestra comparativa Tailscale vs WireGuard self-host, ya sabes que Headscale es la tercera vía — la que combina la UX de Tailscale y la soberanía del self-host WireGuard. La pregunta ya no es "¿es posible?" sino "¿merece la pena invertir el tiempo de setup?". Esta guía responde concretamente, sobre la base de una instancia Headscale corriendo en producción en Contabo desde febrero de 2026.

En el menú: qué es realmente Headscale, cuándo tiene sentido (y cuándo no), instalación paso a paso en Contabo con PostgreSQL y OIDC, configuración de ACLs, trampas en producción que nadie menciona, y costes reales a 36 meses frente a Tailscale Premium. Al final podrás decidir en 5 minutos si invertir los 2-3 días que requiere un setup limpio.

Lo que es realmente Headscale

Headscale es una reimplementación open-source de la API del coordinator de Tailscale, escrita en Go, mantenida principalmente por Juan Font y una comunidad cerrada de contributors. Código fuente: github.com/juanfont/headscale. Licencia: BSD-3.

No es un fork de Tailscale. Es un servidor que habla el mismo protocolo que el coordinator SaaS de Tailscale — lo que significa que los clientes oficiales Tailscale (iOS, Android, macOS, Windows, Linux) pueden apuntar a tu instancia Headscale y comportarse normalmente. Ningún cliente parcheado, ningún binario custom dudoso.

Lo que Headscale gestiona:

• Discovery y distribución de claves — exactamente como el coordinator SaaS.
• Coordinación del NAT traversal — vía relays DERP (puedes usar los relays DERP públicos de Tailscale gratis, o auto-hospedar los tuyos).
• ACLs declarativas — acepta el mismo formato JSON que Tailscale. Misma sintaxis, misma semántica.
• MagicDNS — resolución de node.tailnet.example.com (o el dominio que configures).
• Subnet routes — para exponer un VPC o LAN detrás de un nodo.
• Exit nodes — para enrutar todo el tráfico de internet vía un nodo elegido.

Lo que Headscale NO gestiona (los límites honestos):

• Sin features Premium oficiales: sin grabación de sesión SSH Tailscale, sin consola SSO nativa (configuras OIDC tú mismo), sin GUI admin propietaria (existe un proyecto headscale-ui separado, de terceros).
• La gestión de clientes móviles es más manual — las auth keys deben generarse en CLI.
• El soporte de Tailscale Inc. es inexistente — únicamente community support, GitHub Discussions y Discord.

La promesa es precisa: 90% del valor de Tailscale Premium, por ~5% del coste cash, con 100% de soberanía sobre los datos.

Cuándo Headscale tiene realmente sentido

Headscale no siempre es la respuesta correcta. Aquí va la matriz de decisión construida sobre 8 meses de producción:

Las dos principales razones por las que se despliega Headscale en producción:

1. Soberanía / compliance: el departamento legal o la DSI prohíbe la dependencia SaaS no controlada. Headscale marca la casilla "alojado en Europa, conforme GDPR, ninguna transferencia US". Es el caso en los SaaS B2B europeos en crecimiento.
2. Optimización cash a escala: con 15+ usuarios, Tailscale Premium se vuelven facturas mensuales de 4 cifras. Un VPS Contabo S a 60 €/año + 2-3 días de sysadmin se amortiza en menos de 2 meses.

Si ninguna de estas dos razones se aplica a ti, quédate en Tailscale Premium o WireGuard self-host raw. La vía intermedia solo tiene sentido si está realmente justificada.

Arquitectura elegida en producción

Aquí va la arquitectura desplegada en febrero de 2026 y que sigue corriendo hoy:

[Cliente Tailscale iOS/Android/Linux]
            │
            │ HTTPS (puerto 443)
            ▼
[Reverse proxy Caddy] ──► [Headscale]
            │                    │
            │                    ▼
            │            [PostgreSQL 15]
            │
            └──► [Tailscale DERP relays - público gratuito]

Componentes:

• VPS Contabo S Nuremberg (4 vCPU, 8 GB RAM, 200 GB NVMe, 4,99 €/mes) — ver nuestra reseña Contabo 2026 y el tutorial setup paso a paso para preparar el VPS.
• Headscale 0.24 como coordinator.
• PostgreSQL 15 como backend (vs SQLite por defecto, más robusto a partir de 20 nodos).
• Caddy 2 como reverse proxy con TLS automático Let's Encrypt — Headscale necesita HTTPS, los clientes oficiales lo exigen.
• OIDC vía Authentik (también auto-hospedado, pero Auth0 o Keycloak funcionan igualmente bien).
• Relays DERP públicos Tailscale para el NAT traversal — gratuitos, sin necesidad de auto-hospedar DERP salvo restricción paranoide específica.

Instalación paso a paso en Contabo

Tiempo de setup en un VPS recién provisionado: contar 90 minutos siguiendo los pasos sin titubear. Asumimos Debian 12 (el default de Contabo).

1. Preparación del sistema

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

2. Crear la base PostgreSQL Headscale

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

3. Instalación de Headscale

El paquete .deb oficial es la vía más limpia. Última 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. Configuración Headscale

Edita /etc/headscale/config.yaml. Los parámetros mínimos requeridos:

server_url: https://headscale.tu-dominio.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: PON_UNA_CONTRASEÑA_FUERTE_AQUI

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.tu-dominio.com/application/o/headscale/
  client_id: headscale
  client_secret: OIDC_SECRET_AQUI
  scope: ["openid", "profile", "email"]

Puntos críticos:

• server_url debe estar en HTTPS. Los clientes Tailscale oficiales rechazan HTTP en claro.
• ip_prefixes: 100.64.0.0/10 es el rango CGNAT que usa Tailscale por defecto. No lo cambies salvo que sepas lo que haces.
• oidc: opcional pero fuertemente recomendado en producción. Sin OIDC, vuelves a headscale users create y claves precompartidas.

5. Caddy como reverse proxy

/etc/caddy/Caddyfile:

headscale.tu-dominio.com {
    reverse_proxy 127.0.0.1:8080
}

Reload: systemctl reload caddy. Caddy obtiene automáticamente el certificado Let's Encrypt. Verifica la cadena antes de continuar — los clientes oficiales Tailscale rechazan los certificados auto-firmados.

6. Arrancar Headscale

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

Deberías ver los logs de arranque, después "Listening on 127.0.0.1:8080".

7. Crear un primer usuario y una pre-auth key

headscale users create eric
headscale preauthkeys create --user eric --reusable --expiration 24h

La salida da una clave tskey-auth-xxxxxxxxxxxx. Anótala.

8. Conectar un cliente Tailscale

En un cliente Linux con el cliente Tailscale oficial instalado:

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

El nodo aparece en headscale nodes list. A partir de ahí puedes recuperar su IP 100.x.x.x y empezar a usarlo.

Para iOS/Android: instala la app Tailscale oficial, settings → custom login server → tu URL Headscale. Toca "Sign in", serás redirigido a tu provider OIDC.

Configuración de ACLs en modo producción

Las ACLs son donde Headscale muestra realmente que es "Tailscale-compatible". El archivo JSON acepta la misma sintaxis que las ACLs Tailscale Premium.

Ejemplo de producción (equipo de 5 users con segregación 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 tras cada modificación: headscale acls reload. Headscale valida el JSON antes de aplicar, así que un error de sintaxis nunca rompe el mesh de producción.

Trampas en producción que nadie menciona

Ocho meses de operación de Headscale, aquí las cuatro trampas que nos costaron un fin de semana o más:

1. Saturación del pool de conexiones PostgreSQL. El tamaño del pool Headscale por defecto es 25 conexiones. A partir de 50 nodos simultáneos con reconexiones frecuentes (típico del roaming Wi-Fi en smartphone), alcanzas el límite y las conexiones empiezan a caer. Fix: subir database.postgres.max_open_conns a 100, y configurar max_idle_conns: 10.

2. Los relays DERP públicos Tailscale pueden ser caprichosos en Asia/Australia. Si tienes nodos en esas zonas, la latencia puede dispararse. Solución: auto-hospedar un relay DERP en un VPS en la región. Headscale se encarga de manera transparente — ver la doc DERP oficial.

3. El backup de PostgreSQL es obligatorio y subestimado. Headscale almacena todo en PostgreSQL: nodos, claves públicas, estado de ACLs, mappings OIDC. Si pierdes la DB, pierdes el mesh entero. Pon en marcha pg_dump diario + backup automático hacia S3-compatible (usamos Hetzner Object Storage a 1 €/mes para eso). Restore probado cada 3 meses.

4. Las upgrades binarios de Headscale son suaves pero ocurren breaking changes entre versiones menores. Lee el CHANGELOG antes de pasar de 0.23 a 0.24. El equipo de dev es reactivo en GitHub pero Headscale está en desarrollo activo — asume breaking changes cada ~6 meses.

Costes reales a 36 meses — Headscale vs Tailscale Premium

El cálculo con 10 usuarios, 25 nodos, con hipótesis prudentes:

Headscale gana ~2.250 € sobre 36 meses a 10 users. No es enorme, pero es real — y la brecha crece linealmente con el tamaño del equipo. Con 20 users hablamos de ~8.000 € de ahorro a 3 años. Con 50 users es dinero serio.

Si tu tiempo vale más de 100 €/h, esa brecha se reduce rápido. Si vale menos de 50 €/h (junior, side project, aprendizaje), Headscale gana fácilmente.

Veredicto — cuándo desplegar Headscale en 2026

Despliega Headscale si:

• Tienes restricción de soberanía / GDPR / ninguna transferencia US
• Tu equipo está en 10+ usuarios con horizonte 12+ meses
• Tienes sysadmin en casa o reflejo sysadmin personal
• Tailscale Premium te sale caro pero WireGuard raw te parece demasiado primitivo

Quédate en Tailscale Premium si:

• Tu tiempo vale más de 100 €/h
• Sin restricción de compliance específica
• Prefieres dedicar esos 2-3 días a tu producto

Quédate en WireGuard raw si:

• Estás bajo 5 nodos, setup simple, modo aprendizaje
• Hub-and-spoke responde a todos tus casos de uso

Headscale es la respuesta más subestimada del ecosistema self-hosted VPN en 2026. Hace el 90% del trabajo de Tailscale, en un VPS Contabo a 4,99 €/mes, con soberanía completa. El precio: 2-3 días de setup y un reflejo sysadmin — que se amortiza en menos de 2 meses con 10 users.

Para profundizar

• Tailscale vs WireGuard self-host: cuál elegir en 2026
• Self-host VPN en Contabo: guía completa WireGuard 2026
• Setup VPS Contabo paso a paso para VPN 2026
• Monitoring VPS VPN con Prometheus + Grafana
• Reseña Contabo 2026: feedback honesto de producción

Fuentes y referencias:

• Headscale — código fuente y docs oficiales
• Sitio de documentación Headscale
• Referencia sintaxis ACL Tailscale
• Guía setup DERP server

Publicado el 2026-06-05. Análisis de producción basado en una instancia Headscale 0.24 desplegada en un VPS Contabo S Nuremberg en febrero de 2026 (12 nodos, 5 users, backend PostgreSQL, OIDC vía Authentik). Tarifas según pricing Contabo y Tailscale de mayo de 2026 — verificar antes de decidir. Rendimiento y ahorro reales dependen del tamaño del equipo y la infraestructura existente.

Recordatorio: Headscale, Tailscale y el self-hosting de VPN son perfectamente legales en la UE, EE.UU., Canadá y la mayoría de países democráticos. VPNSmith publica este contenido con fines educativos.