Headscale: tu propio Tailscale self-hosted en 2026

Tailscale es excelente. La experiencia del cliente es de las mejores que vas a encontrar para armar una mesh VPN entre tu laptop, tu homelab, tu teléfono y tus servidores en la nube. WireGuard debajo, MagicDNS para resolver nombres de nodos, exit nodes, ACLs. Funciona. El problema es el servidor de control: está cerrado y corre en infraestructura de Tailscale. Si quieres la misma magia sin la dependencia operacional del SaaS, necesitas Headscale.

Headscale es la implementación open source del servidor de control de Tailscale — escrito en Go por la comunidad, compatible 1:1 con el cliente oficial. Tú lo corres donde quieras, tú defines las ACLs, tú tienes los logs. Esta guía cubre la instalación en Ubuntu 22.04/24.04, la integración con OIDC para SSO, el setup de MagicDNS y los gotchas que aparecen cuando vienes de Tailscale SaaS y asumís cosas que aquí se hacen distinto.

---

Meta description: Headscale es el servidor de control open source de Tailscale. Te permite correr tu mesh VPN sin depender del SaaS, manteniendo el mismo cliente Tailscale. Guía 2026 con instalación en Ubuntu, configuración, OIDC y troubleshooting.

---

Tailscale es excelente. La experiencia del cliente es de las mejores que vas a encontrar para armar una mesh VPN entre tus dispositivos, tu homelab y tus servidores en la nube. Pero todo depende de un servidor de control cerrado que Tailscale corre en su infraestructura. Si quieres la misma magia, mismo cliente, misma red mesh, pero con el control server en tu propio hardware (o tu VPS), existe Headscale: una reimplementación open source del servidor de coordinación de Tailscale, escrita en Go por Juan Font y mantenida por la comunidad desde 2022.

Esta guía es 2026, cubre la versión actual (v0.29.x), instalación en Debian/Ubuntu con el paquete oficial .deb, registro de nodos, OIDC y los problemas reales que vas a encontrar al levantar uno.

TL;DR — ¿Qué es Headscale y cuándo te sirve?

Caso	¿Headscale o Tailscale directo?
Quiero algo que ande en 5 minutos	Tailscale (SaaS, plan personal gratis hasta 100 dispositivos)
Quiero control total sobre la coordinación de mi mesh	Headscale
Necesito features empresariales (SSO, audit logs, compliance)	Tailscale plan comercial
No quiero que un vendor vea los metadatos de mi red	Headscale
Mi ISP bloquea UDP o estoy detrás de CGNAT estricto	Ambos lo resuelven (DERP/relay sobre HTTPS)
Quiero compartir nodos con amigos/familia con poco laburo	Tailscale (un click), Headscale (más manual)

Headscale es el servidor de control. El cliente sigue siendo el binario oficial de Tailscale (tailscale), que se conecta a tu Headscale en vez de a controlplane.tailscale.com. El handshake WireGuard, los keys, el NAT traversal via DERP, el MagicDNS: todo eso lo maneja el cliente. Lo que Headscale reemplaza es la pieza que sabe qué nodos existen, qué keys son válidos, qué nodos pueden hablar entre sí.

Si todavía estás decidiendo entre opciones, tienes Tailscale vs WireGuard y ZeroTier vs Tailscale como referencia previa.

¿Por qué self-hosted en 2026?

Tres razones reales, no teóricas:

1. Privacidad. Tailscale (la empresa) sigue viendo metadatos: qué nodos tienes, cuándo se conectan, qué dominios resolvé MagicDNS, qué subnets anunciás. Si te importa esa superficie, sacala.
2. Compliance / data residency. Algunas empresas o países requieren que el control plane quede en infraestructura propia. Headscale te lo da gratis; el equivalente comercial (NetBird, Firezone) cobra.
3. Sin vendor lock-in. El cliente Tailscale es open source (BSD-3) y habla el mismo protocolo contra Headscale. Si algún día Tailscale desaparece o te deja de gustar su plan, migrás los nodos a otro Headscale o vuelves al SaaS cambiando solo --login-server.

Lo que no te da Headscale que sí tiene Tailscale plan comercial: Tailscale Funnel, Tailscale Serve, App Connectors, autogroup:self en ACLs, SCIM provisioning, sync de grupos SSO. Si alguna de esas te bloquea un proyecto, Headscale no es para ti todavía.

Requisitos antes de empezar

• Un servidor con IP pública, idealmente con puerto fijo (o DDNS funcional). Un VPS chico de 1 vCPU / 512 MB RAM / 10 GB SSD alcanza para 50-100 nodos sin problema. OPNsense, pfSense, o un container LXC en tu Proxmox con NAT 1:1 también funcionan.
• Un dominio que apunte a esa IP, para el certificado TLS (Let’s Encrypt via Caddy o Traefik). Los clientes Tailscale exigen HTTPS para el login-server. Subdominio wildcard no es necesario; vpn.tudominio.com alcanza.
• Acceso a internet saliente desde los nodos (NAT saliente está bien, no necesitas port forward).
• Sistema operativo soportado: Ubuntu 22.04+ o Debian 12+ para el paquete .deb. Otras distros funcionan compilando el binario o usando el container oficial (Docker/Podman).

verifica la versión actual antes de seguir. Al momento de escribir esto (agosto 2026) la release estable es v0.29.3, publicada el 29 de julio de 2026.

# verifica qué tienes en el servidor donde vas a instalar
cat /etc/os-release | grep -E "PRETTY_NAME|VERSION_CODENAME"
# Ubuntu 22.04 LTS (Jammy Jellyfish)   <- OK
# Ubuntu 24.04 LTS (Noble Numbat)      <- OK
# Debian GNU/Linux 12 (bookworm)       <- OK

Si tu distro es más vieja (Ubuntu 20.04, Debian 11), el binario anda igual pero el paquete .deb no está soportado oficialmente y vas a tener fricciones con systemd. Mejor actualizar antes de seguir.

Instalación con el paquete .deb oficial (recomendado)

El proyecto mantiene un .deb que crea el usuario headscale dedicado, deja el binario en /usr/bin/headscale, la config en /etc/headscale/config.yaml, los datos en /var/lib/headscale/ y la unit file de systemd. Es el path con menos sorpresa.

Paso 1: bajar e instalar el paquete

# fíjate la última versión en https://github.com/juanfont/headscale/releases
# (no incluir el prefijo "v" en HEADSCALE_VERSION)
HEADSCALE_VERSION="0.29.3"
HEADSCALE_ARCH="amd64"
wget --output-document=headscale.deb 
  "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
sudo apt install -y ./headscale.deb

apt install ./archivo.deb resuelve las dependencias (ca-certificates, iptables, etc.) automáticamente y a la vez te deja el paquete listado en el dpkg database, lo que facilita upgrades futuros con apt upgrade. Si tuvieras error de GPG o firma inválida, el repo de GitHub publica las checksums SHA256 en cada release; puedes validar con sha256sum -c checksums.txt si quieres cinturón y tirantes.

Paso 2: editar la configuración base

sudo nano /etc/headscale/config.yaml

Lo mínimo que tienes que cambiar antes de arrancar el servicio:

server_url: https://vpn.tudominio.com
listen_addr: 0.0.0.0:443
metrics_listen_addr: 127.0.0.1:9090
# Para evitar el warning de unix socket group-accessible, dejá así
unix_socket: /var/run/headscale/headscale.sock
unix_socket_permission: "0770"
# Base de datos — SQLite alcanza para homelabs chicos
database:
  type: sqlite
  sqlite:
    path: /var/lib/headscale/db.sqlite
# DNS y prefix (MagicDNS)
prefixes:
  allocation: sequential
  cidr: 100.64.0.0/10
base_domain: headscale.tudominio.com
magic_dns: true

El prefixes.cidr define la subred privada donde caen tus nodos. El default 100.64.0.0/10 es el rango CGNAT que usa Tailscale también, así que los rangos no chocan con nada de internet y tus nodos no quedan alcanzables desde fuera.

magic_dns: true activa la resolución automática: el nodo mi-servidor se vuelve mi-servidor.headscale.tudominio.com y puedes llegar por nombre sin editar /etc/hosts.

Paso 3: reverse proxy con HTTPS

El cliente Tailscale exige HTTPS en el login-server. La forma más rápida es Caddy (auto-TLS con Let’s Encrypt, cero config):

sudo apt install -y caddy
sudo tee /etc/caddy/Caddyfile <<'EOF'
vpn.tudominio.com {
    reverse_proxy 127.0.0.1:443
}
EOF
sudo systemctl reload caddy

Si prefieres nginx o Traefik, la idea es la misma: terminás TLS en el proxy y le pasás el tráfico limpio al Headscale en 127.0.0.1:443. Hay una config oficial de referencia para nginx en la documentación de Headscale si vas por ese camino.

Paso 4: arrancar y verificar

sudo systemctl enable --now headscale
sudo systemctl status headscale

El status tiene que decirte active (running) sin errores en las últimas 20 líneas. Si ves failed, casi siempre es una de estas tres cosas: (1) el puerto 443 está ocupado por otro proceso, (2) la base de datos no se puede crear en /var/lib/headscale/ por permisos, o (3) la server_url no matchea con el dominio real por el que estás llegando. revisa journalctl -u headscale -n 50 --no-pager para el error exacto.

Verificación final desde afuera:

curl -I https://vpn.tudominio.com/health
# HTTP/2 200
# ...

/health responde 200 cuando el server está vivo y respondiendo el protocolo gRPC-Web que habla el cliente. Si te tira 404, el TLS terminó pero el upstream no está conectado; si te tira connection refused, ni siquiera estás llegando al server.

Registrar nodos

Hay dos métodos oficiales: web auth (interactivo, manual) y pre-auth keys (scriptable, ideal para automatizar deploys). Ambos requieren un usuario en Headscale primero.

Crear el usuario “dueño” de los nodos

# Como root o vía sudo (Headscale deja el unix socket solo accesible a root/grupo headscale)
sudo headscale users create roger

roger es el nombre del usuario headscale (no el system user). Es el dueño lógico de los nodos. puedes tener varios usuarios; en setups familiares uno solo alcanza. Para verificar:

sudo headscale users list
# ID | Name | Created
# 1  | roger | 2026-08-19 22:14:33

Método 1: web auth (un nodo a la vez)

En el cliente (la máquina que quieres sumar a la mesh):

# instala el cliente Tailscale según tu OS
# Ubuntu/Debian:
curl -fsSL https://tailscale.com/install.sh | sh
# Fedora/RHEL:
sudo dnf install -y tailscale
# macOS / Windows: bajá el .pkg / .msi desde tailscale.com
# Levantá el daemon
sudo systemctl enable --now tailscaled
# Conectá a TU Headscale (no a tailscale.com)
sudo tailscale up --login-server https://vpn.tudominio.com

Esto te va a tirar una URL tipo https://vpn.tudominio.com/register/machinekey:abc123. La abres en el navegador, te muestra el nodo pendiente con su nombre, hostname y OS, y le das “Register”. En el server:

sudo headscale nodes register --user roger --key machinekey:abc123

Listo. El nodo aparece en sudo headscale nodes list con su IP del rango 100.64.0.0/10 y puedes llegar a él desde cualquier otro nodo de la mesh.

Método 2: pre-auth keys (automatizable, ideal para deploys)

generas una key una vez (con expiración corta), la pasás a un script de provisioning, y todos los nodos nuevos se registran sin intervención manual:

# En el server, generar la key (1 hora, reusable, efímera)
sudo headscale preauthkeys create --user 1 --expiration 1h --single_use --reusable
# Generated pre-auth key: abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

En cada cliente nuevo (script de bootstrap, cloud-init, lo que sea):

sudo tailscale up 
  --login-server https://vpn.tudominio.com 
  --authkey abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Sin navegador, sin prompt, sin tocar el server. Para producción es lo que vas a usar. Si quieres tags (servidor, laptop, dev, prod), pasás --advertise-tags=tag:server y la tag queda atada al nodo en el registro.

Configuración útil que vas a querer

Exit node (toda la red sale por el servidor)

Si quieres que, cuando estás en un café, TODO tu tráfico salga por tu casa (o tu VPS):

# En el nodo que va a ser exit node
sudo tailscale up --login-server https://vpn.tudominio.com --advertise-exit-node
# En el server, aprobarlo
sudo headscale nodes approve-routes --node-id 1 --routes 0.0.0.0/0

Desde otra máquina de la mesh:

sudo tailscale up --login-server https://vpn.tudominio.com --exit-node=<nombre-o-ip>

Para verificar que efectivamente estás saliendo por el exit node: curl ifconfig.me tiene que devolver la IP pública del servidor, no la del café.

Subnet router (llegar a tu LAN desde la mesh)

Si quieres que tu mesh VPN te deje acceder a 192.168.1.0/24 de tu casa sin instalar Tailscale en cada device de la red:

# En el nodo subnet router (Raspberry Pi, mini PC, lo que sea)
sudo tailscale up --login-server https://vpn.tudominio.com 
  --advertise-routes=192.168.1.0/24
# En el server
sudo headscale nodes approve-routes --node-id 5 --routes 192.168.1.0/24

habilita IP forwarding en ese nodo (echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-tailscale.conf && sudo sysctl -p). Si el subnet router está en un container LXC, asegurate que el host tenga IP forwarding activo también.

MagicDNS y nombres custom

Si dejaste magic_dns: true en la config, los nodos ya se resuelven automáticamente. Para tener nombres cortos (sin el dominio), configura search domain en cada cliente:

sudo tailscale up --login-server https://vpn.tudominio.com --accept-dns=true

Y para forzar DNS específicos por nodo (por ejemplo, que el servidor DNS de tu homelab atienda ciertas queries):

# /etc/headscale/config.yaml
dns:
  magic_dns: true
  base_domain: headscale.tudominio.com
  nameservers.global:
    - 1.1.1.1
    - 9.9.9.9
  nameservers.split:
    - routes:
        - 192.168.1.0/24
      nameservers:
        - 192.168.1.1   # DNS interno de tu LAN

OIDC para que tus usuarios se autentifiquen con Google/GitHub/Authentik

Una de las features más potentes de Headscale v0.23+ es OIDC nativo. En vez de manejar usuarios con headscale users create, tus nodos se registran contra un proveedor externo y Headscale valida el token.

# /etc/headscale/config.yaml
oidc:
  only_start_if_oidc_is_available: true
  issuer: "https://accounts.google.com"   # o tu Keycloak/Authentik/Auth0
  client_id: "tu-client-id.apps.googleusercontent.com"
  client_secret: "tu-secret"
  scope: ["openid", "email", "profile"]
  extra_params:
    domain_hint: tudominio.com   # si usas Google Workspace, limita a tu dominio
  allowed_domains:
    - tudominio.com
  strip_email_domain: true

Con allowed_domains, solo usuarios de tu dominio Google (o los que matcheen en tu IdP) pueden registrarse. strip_email_domain: true mapea [email protected] → usuario headscale roger automáticamente.

Para activarlo en el cliente:

sudo tailscale up --login-server https://vpn.tudominio.com [email protected]

El --operator le dice a Headscale qué usuario OAuth es el dueño del nodo cuando se aprueba vía web.

Troubleshooting: lo que realmente pasa

Después de levantar varios Headscale en producción estos meses, estos son los problemas reales que vas a hitear. Anotalos porque la documentación oficial no siempre los cubre.

“MagicDNS no resuelve los nombres de mis nodos”

Si ping mi-servidor desde otro nodo devuelve “Name or service not known” pero ping 100.64.0.2 sí anda, el problema es DNS. Tres causas típicas:

1. El cliente Tailscale no está aceptando DNS de Headscale. verifica con tailscale debug o tailscale status --json | jq .Settings. El campo AcceptDNS tiene que ser true. Si está false, agregá --accept-dns=true al tailscale up.
2. El systemd-resolved de Ubuntu 22.04+ se pelea con Tailscale. Si ves que el resolved tiene como upstream 127.0.0.1:53 después de tailscale up, está bien. Si quedó con los DNS del ISP, algo no se levantó. Solución: sudo systemctl restart systemd-resolved tailscaled.
3. El firewall del nodo bloquea UDP 53 a 100.64.0.0/10. El MagicDNS resuelve sobre UDP 53 entre nodos. ufw allow in from 100.64.0.0/10 to any port 53 lo destraba.

“El cliente se conecta pero no llega a otros nodos (no handshake)”

Esto casi siempre es uno de tres:

• El servidor Headscale quedó pegado en un loop de restart. La v0.29.0 tuvo un bug documentado en Reddit donde el proceso entraba en crash loop por cambios en el schema de la DB al upgrade. Fix: volver a v0.28.0, hacer dump de la DB, upgrade limpio a v0.29.x. Si estás en v0.29.x y ves el loop, journalctl -u headscale --since "5 minutes ago" te muestra el panic exacto.
• El DERP no está accesible. Tailscale usa relays DERP sobre HTTPS (puerto 443) cuando no puede hacer NAT traversal directo. Si tu server bloquea outbound HTTPS a derp.tailscale.com o equivalente, la mesh queda partida. verifica con tailscale status --json | jq .PeerState que muestra Relay para los peers en lugar de Direct.
• El firewall del server bloquea inbound 443. Obvio pero pasa. sudo ss -tlnp | grep :443 tiene que mostrar el proceso de Headscale o el reverse proxy escuchando.

“El nodo se registra pero no aparece en headscale nodes list“

Espera 3-5 segundos. Headscale es asíncrono en el sentido de que la primera vez que un nodo se conecta hay un handshake gRPC que puede tardar. Si después de 30 segundos sigue sin aparecer, hay un mismatch de versión entre el cliente Tailscale y el server Headscale.

Las versiones viejas de Tailscale (anteriores a 1.34) no hablan el protocolo completo contra Headscale v0.23+. verifica:

tailscale version
# Report:
# 	1.78.1 (basado en commit abc123)
# ...

Y en el server:

headscale version
# 0.29.3

Si tu cliente es < 1.40, actualizá con sudo apt update && sudo apt upgrade tailscale (Ubuntu) o bajando el .msi/.pkg más reciente. Headscale 0.29.x requiere cliente Tailscale ≥ 1.50 por los cambios en el modelo de identidad (tags-as-identity que rompió compatibilidad hacia atrás en 0.29.0).

“El preauthkey me dice ‘invalid’ apenas lo uso”

Dos causas:

1. La key expiró. El --expiration 1h es en horario del server. Si el server está en otra timezone, ajustá. usa --expiration 24h para evitar sorpresas.
2. Single-use vs reusable. Si pusiste --single_use (default), el primer nodo que la usa la consume. Si quieres una key para muchos nodos, agregá --reusable. Si quieres una key por nodo pero quieres que varias machines la compartan, dejá --single_use y generá varias.

“Quiero que un nodo no pueda ver otros nodos”

ACLs. Definís un policy file en policy.path y Headscale lo aplica al handshake. Ejemplo: solo el servidor de backups puede hablar con todos los demás, las laptops solo entre sí:

# /etc/headscale/policy.yaml
acls:
  - action: accept
    src:
      - "tag:server"
    dst:
      - "*:*"
  - action: accept
    src:
      - "tag:laptop"
    dst:
      - "tag:laptop:*"
      - "tag:server:22"

Para que esto funcione, los nodos tienen que tener tags (tailscale up --advertise-tags=tag:server) y la config de Headscale tiene que tener tagOwners definidas en la policy. Antes de v0.26 esto no era necesario; desde ahí, si una tag no tiene owner declarado, las ACLs que la usen se ignoran silenciosamente. Es un foot-gun clásico.

Actualizar Headscale sin romper nada

El upgrade entre versiones menores (0.29.0 → 0.29.3) es indoloro: bajás el .deb nuevo, sudo apt install ./headscale_X.Y.Z.deb, sudo systemctl restart headscale. La DB migra sola al arrancar si hay cambios de schema.

Entre versiones mayores (0.28.x → 0.29.x) hay que leer el CHANGELOG. v0.29.0 introdujo “Tags as identity” que es incompatible hacia atrás: si tienes tags y/o ACLs armadas en 0.28, el upgrade te pide reescribir el policy.yaml con tagOwners. El comando headscale nodes migrate te ayuda si venís de v0.22 o anteriores.

Backup antes de upgradear:

sudo systemctl stop headscale
sudo cp /var/lib/headscale/db.sqlite /var/backups/headscale-$(date +%F).sqlite
sudo systemctl start headscale

Tarda 2 segundos en un homelab chico y te salva si la migración sale mal.

¿Y Headplane, el GUI web?

Headplane es un proyecto separado de la comunidad que expone una UI web para administrar nodos, usuarios y ACLs. Si te cansa la línea de comandos, vale la pena. Es un binario Go que corre como proceso aparte, se conecta al unix socket de Headscale y te da una interfaz moderna. La instalación es apt install headplane o un container, y la config es trivial.

Ojo: Headplane no es oficial, no tiene el mismo SLA de releases que Headscale, y algunos features avanzados (OIDC con mapping complejo de grupos) no están cubiertas todavía. Para gestión básica de nodos y ver qué está conectado, es excelente.

Cuándo NO usar Headscale

Para no venderte humo: Headscale no es la respuesta para todos los casos.

• Empresas con compliance serio. Aunque Headscale es open source, no tiene audit logs firmados, no tiene SCIM, no tiene SSO group sync. Si tu auditor te pide alguna de esas, pagás Tailscale plan comercial o mirás NetBird que tiene más features empresariales out of the box.
• Equipos grandes donde todos se conectan a todo. Tailscale tiene una consola de admin que hace todo eso con clicks. Con Headscale vas a editar YAML para cada cambio de permiso.
• Mobile-first. El cliente Tailscale en iOS/Android funciona perfecto contra Headscale, pero la experiencia de invitar a un usuario nuevo desde el celular es pésima: no hay app companion. Para uso personal/familiar está bien; para “invitar a un cliente a ver un servicio” no.
• Si no te importa el control server. En serio. Si Tailscale SaaS te sirve, pagalo (o usa el plan gratis hasta 100 devices) y dedicate a otra cosa. El tiempo que vas a invertir manteniendo tu Headscale (upgrades, monitoring, backups) tiene un costo real.

Resumen

Headscale es la pieza que faltaba entre “VPN mesh WireGuard a mano, configurando keys y nodos a pedal” y “SaaS que sabe toda mi topología”. Te queda el cliente oficial Tailscale (que es excelente), te queda el protocolo abierto, y el control server lo movés a donde tú quieras: un VPS de $5/mes, un LXC en tu Proxmox, un NUC en tu homelab. El setup inicial te lleva 30 minutos si ya tienes un dominio y un reverse proxy. La operación diaria es prácticamente cero.

Si tuviéramos que poner una advertencia: la versión 0.29 todavía está en la zona “production-ready pero con asteriscos”. El bug del restart-loop en 0.29.0 fue real y hubo gente en producción que tuvo que retroceder. Antes de desplegarlo en algo crítico, pruébalo en un VPS descartable, levantá 3-4 nodos (laptop, servidor, mobile), y verifica que el upgrade entre versiones te funciona. Una vez que lo tienes estable, es una de las mejores piezas de infra self-hosted que existen.

Preguntas frecuentes

Lee también

• Guía Fedora 44: Novedades, Instalación y Upgrade para Sysadmins Linux
• Configura VLANs en Linux con nmcli: Guía paso a paso para sysadmins
• Protege tu SSH: Guía esencial para configurar Fail2ban en Linux
• Guía Definitiva: Configura Kubernetes con kubeadm en Ubuntu para Sysadmins Linux
• Configura Prometheus y Grafana: Guía DevOps para SysAdmins Linux