headscale

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

Junte-se ao nosso servidor Discord para conversar.

Nota: Sempre selecione a mesma tag do GitHub que a versão lançada que você usa para garantir que você 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 as 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 é o Tailscale

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

Tudo no Tailscale é Open Source, exceto os clientes com 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 Wireguard para os nós na rede Tailscale. Ele atribui os endereços IP dos clientes, cria as fronteiras 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 em termos de usuários privados ou de uma organização.

Objetivo de design

O Headscale visa implementar uma alternativa auto-hospedada e open source ao servidor de controle do Tailscale. O objetivo do Headscale é proporcionar a auto-hospedadores e entusiastas um servidor open source que eles possam usar para seus projetos e laboratórios. Ele implementa um escopo restrito, 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 considera útil, há botões de patrocínio e doação disponíveis no repositório.

Recursos

Por favor, consulte "Features" na documentação.

Suporte a sistemas operacionais de clientes

Por favor, consulte "Client and operating system support" na documentação.

Executando o headscale

Observe que não oferecemos suporte nem incentivamos o uso de proxies reversos e contêineres para executar o Headscale.

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

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

Builds a partir do main

Builds de desenvolvimento a partir do branch main estão disponíveis como imagens de contêiner e binários. Consulte a documentação de builds 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 tem permissão para dedicar horas de trabalho contribuindo para o projeto. As contribuições deste mantenedor são revisadas por outros mantenedores.

Os mantenedores trabalham juntos para definir a direção do projeto. O princípio subjacente é servir a comunidade de auto-hospedadores, entusiastas e hobistas - mantendo um projeto sustentável.

Contribuindo

Por favor, leia o arquivo CONTRIBUTING.md.

Dê também uma olhada no nosso AI_POLICY.md.

Requisitos

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

Recomendamos usar o Nix para configurar um ambiente de desenvolvimento. Isso pode ser feito com nix develop, que instalará as ferramentas e fornecerá 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 o 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 os formatadores do golangci-lint (gofumpt, gci, goimports). Configure seu editor para executar as ferramentas durante o desenvolvimento e certifique-se de executar make lint e make fmt antes de commitar qualquer código.

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

A documentação é formatada com mdformat.

O resto (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
• Ferramentas de Protobuf

Instale e ative:

nix develop

Testes e compilação

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

make generate

Nota: Verifique 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 usar Nix para o gerenciamento de dependências, a fim de 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á você se alguma ferramenta necessária estiver faltando e sugerirá executar nix develop. Execute make help para ver todos os alvos disponíveis.

Colaboradores

Feito com contrib.rocks.