headscale v0.29.3

Uma implementação open source, auto-hospedada do servidor de controle do Tailscale.

Junte-se ao nosso servidor no Discord para conversar.

Nota: Sempre selecione a mesma tag do GitHub que a versão lançada que você usa para garantir que tenha a configuração de exemplo correta. O branch main pode conter alterações não lançadas. A documentação está disponível para versões estável e de desenvolvimento:

• Documentação para a versão estável
• Documentação para a versão de desenvolvimento

O que é Tailscale

Tailscale é uma VPN moderna construída sobre o Wireguard. Ela funciona como uma rede overlay entre os computadores das suas redes - usando NAT traversal.

Tudo no Tailscale é Open Source, exceto os clientes GUI para sistemas operacionais proprietários (Windows e macOS/iOS) e o servidor de controle.

O servidor de controle funciona como um ponto de troca de chaves públicas do Wireguard para os nós na rede Tailscale. Ele atribui os endereços IP dos clientes, cria os limites entre cada usuário, permite o compartilhamento de máquinas entre usuários e expõe as rotas anunciadas dos seus nós.

Uma rede Tailscale (tailnet) é uma rede privada que o Tailscale atribui a um usuário, seja ele usuário particular ou uma organização.

Objetivo do design

Headscale visa implementar uma alternativa open source auto-hospedada ao servidor de controle do Tailscale. O objetivo do Headscale é fornecer a auto-hospedeiros e amadores um servidor open source que eles possam usar para seus projetos e laboratórios. Ele implementa um escopo estreito, uma única rede Tailscale (tailnet), adequada para uso pessoal ou uma pequena organização open source.

Apoiando o Headscale

Se você gosta do headscale e o acha útil, há botões de patrocínio e doação disponíveis no repositório.

Funcionalidades

Por favor, veja "Funcionalidades" na documentação.

Suporte a sistemas operacionais cliente

Por favor, veja "Suporte a cliente e sistema operacional" na documentação.

Executando o headscale

Por favor, observe que não suportamos nem incentivamos o uso de proxies reversos e containers para executar o Headscale.

Por favor, dê uma olhada na documentação.

Para usuários do NixOS, um módulo está disponível em nix/.

Compilações a partir do main

Compilações de desenvolvimento do branch main estão disponíveis como imagens de container e binários. Veja a documentação de compilações de desenvolvimento para detalhes.

Palestras

• Fosdem 2026 (vídeo): Headscale & Tailscale: The complementary open source clone
  • apresentado por Kristoffer Dalby
• Fosdem 2023 (vídeo): Headscale: How we are using integration testing to reimplement Tailscale
  • apresentado por Juan Font Alonso e Kristoffer Dalby

Aviso legal

Este projeto não é associado à Tailscale Inc.

No entanto, um dos mantenedores ativos do Headscale é empregado pela Tailscale e ele tem permissão para usar horas de trabalho contribuindo para o projeto. Contribuições deste mantenedor são revisadas por outros mantenedores.

Os mantenedores trabalham juntos para definir a direção do projeto. O princípio fundamental é servir a comunidade de auto-hospedeiros, entusiastas e amadores - enquanto se mantém um projeto sustentável.

Contribuindo

Por favor, leia o arquivo CONTRIBUTING.md.

Requisitos

Para contribuir com o headscale você precisará da versão mais recente do Go e do Buf (gerador de Protobuf).

Recomendamos o uso do Nix para configurar um ambiente de desenvolvimento. Isso pode ser feito com nix develop, que instalará as ferramentas e lhe dará um shell. Isso garante que você terá o mesmo ambiente de desenvolvimento que os mantenedores do headscale.

Estilo de código

Para garantir alguma consistência com um número crescente de contribuições, este projeto adotou regras de linting e estilo/formatação:

O código Go é verificado com golangci-lint e formatado com golines (largura 88) e gofumpt. Por favor, configure seu editor para executar as ferramentas durante o desenvolvimento e certifique-se de executar make lint e make fmt antes de submeter qualquer código.

O código Proto é verificado com buf e formatado com clang-format.

Os documentos são formatados com mdformat.

O restante (Markdown, YAML, etc) é formatado com prettier.

Confira o .golangci.yaml e o Makefile para ver a configuração específica.

Instalar ferramentas de desenvolvimento

• Go
• Buf
• Protobuf tools

Instale e ative:

nix develop

Testando e compilando

Algumas partes do projeto exigem a geração de código Go a partir de Protobuf (se alterações forem feitas em proto/) e deve ser (re)gerado com:

make generate

Nota: Por favor, inclua as alterações de gen/ em um commit separado para facilitar a revisão.

Para executar os testes:

make test

Para compilar o programa:

make build

Fluxo de trabalho de desenvolvimento

Recomendamos o uso do Nix para gerenciamento de dependências para garantir que você tenha todas as ferramentas necessárias. Se preferir gerenciar as dependências por conta própria, você pode usar o Make diretamente:

Com Nix (recomendado):

nix develop
make test
make build

Com suas próprias dependências:

make test
make build

O Makefile avisará se alguma ferramenta necessária estiver faltando e sugerirá executar nix develop. Execute make help para ver todos os alvos disponíveis.

Contribuidores

Feito com contrib.rocks.