headscale

Una implementación de código abierto y autoalojada del servidor de control de Tailscale.

Únete a nuestro servidor de Discord para conversar.

Nota: Selecciona siempre la misma etiqueta de GitHub que la versión publicada que uses para asegurarte de tener la configuración de ejemplo correcta. La rama main puede contener cambios no publicados. La documentación está disponible para las versiones estable y de desarrollo:

• Documentación para la versión estable
• Documentación para la versión de desarrollo

¿Qué es Tailscale?

Tailscale es una VPN moderna construida sobre Wireguard. Funciona como una red superpuesta entre los ordenadores de tus redes, utilizando NAT traversal.

Todo en Tailscale es de código abierto, excepto los clientes GUI para sistemas operativos propietarios (Windows y macOS/iOS) y el servidor de control.

El servidor de control funciona como un punto de intercambio de claves públicas de Wireguard para los nodos en la red Tailscale. Asigna las direcciones IP de los clientes, crea los límites entre cada usuario, permite compartir máquinas entre usuarios y expone las rutas anunciadas de tus nodos.

Una red Tailscale (tailnet) es una red privada que Tailscale asigna a un usuario en términos de usuarios privados o una organización.

Objetivo de diseño

Headscale tiene como objetivo implementar una alternativa autoalojada y de código abierto al servidor de control de Tailscale. El objetivo de Headscale es proporcionar a los autoalojadores y aficionados un servidor de código abierto que puedan usar para sus proyectos y laboratorios. Implementa un alcance limitado, una única red Tailscale (tailnet), adecuada para uso personal o una pequeña organización de código abierto.

Apoyando a Headscale

Si te gusta headscale y te resulta útil, hay botones de patrocinio y donación disponibles en el repositorio.

Características

Consulta "Características" en la documentación.

Soporte de sistema operativo cliente

Consulta "Soporte de cliente y sistema operativo" en la documentación.

Ejecutando headscale

Ten en cuenta que no apoyamos ni fomentamos el uso de proxies inversos y contenedores para ejecutar Headscale.

Échale un vistazo a la documentación.

Para usuarios de NixOS, hay un módulo disponible en nix/.

Compilaciones desde main

Las compilaciones de desarrollo desde la rama main están disponibles como imágenes de contenedor y binarios. Consulta la documentación de compilaciones de desarrollo para más detalles.

Charlas

• Fosdem 2026 (video): Headscale & Tailscale: The complementary open source clone
  • presentado por Kristoffer Dalby
• Fosdem 2023 (video): Headscale: How we are using integration testing to reimplement Tailscale
  • presentado por Juan Font Alonso y Kristoffer Dalby

Aviso legal

Este proyecto no está asociado con Tailscale Inc.

Sin embargo, uno de los mantenedores activos de Headscale está empleado por Tailscale y se le permite dedicar horas laborales para contribuir al proyecto. Las contribuciones de este mantenedor son revisadas por otros mantenedores.

Los mantenedores trabajan juntos para establecer la dirección del proyecto. El principio subyacente es servir a la comunidad de autoalojadores, entusiastas y aficionados, manteniendo un proyecto sostenible.

Contribuir

Por favor, lee el archivo CONTRIBUTING.md.

Requisitos

Para contribuir a headscale necesitarías la última versión de Go y Buf (generador de Protobuf).

Recomendamos usar Nix para configurar un entorno de desarrollo. Esto se puede hacer con nix develop, que instalará las herramientas y te dará un shell. Esto garantiza que tendrás el mismo entorno de desarrollo que los mantenedores de headscale.

Estilo de código

Para asegurar cierta consistencia con un número creciente de contribuciones, este proyecto ha adoptado reglas de linting y estilo/formato:

• El código Go se lint con golangci-lint y se formatea con golines (ancho 88) y gofumpt.
• Configura tu editor para ejecutar las herramientas mientras desarrollas y asegúrate de ejecutar make lint y make fmt antes de subir cualquier código.
• El código Proto se lint con buf y se formatea con clang-format.
• Los docs se formatean con mdformat.
• El resto (Markdown, YAML, etc.) se formatea con prettier.
• Revisa el .golangci.yaml y el para ver la configuración específica.

Instalar herramientas de desarrollo

• Go
• Buf
• Protobuf tools

Instala y activa:

nix develop

Pruebas y compilación

Algunas partes del proyecto requieren la generación de código Go a partir de Protobuf (si se realizan cambios en proto/) y debe (re)generarse con:

make generate

Nota: Por favor, incluye los cambios de gen/ en un commit separado para facilitar la revisión.

Para ejecutar las pruebas:

make test

Para compilar el programa:

make build

Flujo de trabajo de desarrollo

Recomendamos usar Nix para la gestión de dependencias para asegurarte de tener todas las herramientas necesarias. Si prefieres gestionar las dependencias tú mismo, puedes usar Make directamente:

Con Nix (recomendado):

nix develop
make test
make build

Con tus propias dependencias:

make test
make build

El Makefile te advertirá si faltan herramientas necesarias y sugerirá ejecutar nix develop. Ejecuta make help para ver todos los objetivos disponibles.

Contribuidores

Hecho con contrib.rocks.