Headscale self-host: o plano de controlo soberano do Tailscale (2026)

Se já leu a nossa comparação Tailscale vs WireGuard self-host, já sabe que o Headscale é o terceiro caminho - aquele que combina a experiência de utilizador do Tailscale com a soberania do self-host do WireGuard. A questão já não é "é possível?", mas "vale a pena o tempo de configuração?". Este guia responde concretamente, com base numa implementação padrão do Headscale num VPS do Contabo.

Plano: o que é realmente o Headscale, quando faz sentido (e quando não faz), instalação passo a passo no Contabo com PostgreSQL e OIDC, configuração de ACL, as armadilhas de produção que ninguém avisa, e custos de 36 meses vs Tailscale Premium. No final, poderá decidir em 5 minutos se vale a pena investir os 2-3 dias que uma configuração limpa exige.

Está a pesar o Headscale contra o próprio serviço gerido? A nossa comparação Tailscale vs Headscale mostra as funções em falta, o custo a 3 anos e um veredicto por tamanho de equipa.

Ainda não escolheu o VPS? A nossa comparação Melhor VPS para uma VPN compara oito fornecedores para auto-alojar o WireGuard pelo preço que realmente paga, incluindo as duas rubricas que mudam a classificação: IPv4 paga e limitação de velocidade.

Ainda não escolheu o VPS? A nossa comparação Melhor VPS para uma VPN compara oito fornecedores para auto-alojar o WireGuard pelo preço que realmente paga, incluindo as duas rubricas que mudam a classificação: IPv4 paga e limitação de velocidade.

O que é realmente o Headscale

Headscale é uma reimplementação open-source da API do coordenador do Tailscale, escrita em Go, mantida principalmente por Juan Font e uma comunidade de colaboradores dedicada. Código fonte: github.com/juanfont/headscale. Licença: BSD-3.

Não é um fork do Tailscale. É um servidor que fala o mesmo protocolo que o coordenador SaaS do Tailscale - o que significa que os clientes oficiais do Tailscale (iOS, Android, macOS, Windows, Linux) podem ser direcionados para a sua instância do Headscale e funcionarão normalmente. Não há cliente modificado, nem binário personalizado duvidoso.

O que o Headscale gere:

• Descoberta de pares e distribuição de chaves - exatamente como o coordenador SaaS.
• Coordenação de travessia NAT - via relés DERP (pode usar os relés públicos DERP do Tailscale gratuitamente, ou auto-hospedar os seus próprios).
• ACLs declarativas - aceita o mesmo formato JSON de ACL que o Tailscale. Mesma sintaxe, mesma semântica.
• MagicDNS - resolução de node.tailnet.example.com (ou qualquer domínio que configure).
• Rotas de sub-rede - para expor uma VPC ou LAN atrás de um nó.
• Nós de saída - para rotear todo o tráfego da internet através de um nó escolhido.

O que o Headscale NÃO gere (os limites honestos):

• Sem funcionalidades Premium oficiais: sem gravação de sessões SSH do Tailscale, sem consola SSO nativa (configura OIDC por si mesmo), sem GUI administrativa proprietária (existe um projeto separado headscale-ui, de terceiros).
• Gestão de clientes móveis é mais manual - chaves de autenticação devem ser geradas via CLI.
• Suporte da Tailscale Inc. é inexistente - apenas suporte comunitário, GitHub Discussions e Discord.

A promessa é precisa: a maior parte do valor do Tailscale Premium, pelo preço de um pequeno VPS, com um plano de controlo que lhe pertence.

Quando o Headscale realmente faz sentido

O Headscale nem sempre é a resposta certa. Aqui está a matriz de decisão para decidir:

As duas principais razões pelas quais as pessoas implementam o Headscale em produção:

1. Soberania / conformidade: departamento jurídico ou DSI proíbe dependência SaaS descontrolada. O Headscale verifica a caixa "hospedado na Europa, compatível com GDPR, sem transferência para os EUA". É o caso em SaaS B2B regulado em crescimento na UE.
2. Otimização de custos em escala: com 15+ utilizadores, o Tailscale Premium torna-se faturas mensais de quatro dígitos. Um Contabo Cloud VPS 4 a €66/ano + 2-3 dias de tempo de administração de sistemas custa menos em dinheiro; a tabela a 36 meses mais abaixo mostra o cálculo completo.

Se nenhuma dessas motivações se aplica à sua situação, mantenha-se no Tailscale Premium ou no WireGuard bruto. O meio-termo só faz sentido se for realmente justificado.

Arquitetura escolhida para produção

Aqui está a arquitetura de referência que este guia pressupõe:

[Cliente Tailscale iOS/Android/Linux]
            │
            │ HTTPS (porta 443)
            ▼
[Proxy reverso Caddy] ──► [Headscale]
            │                    │
            │                    ▼
            │            [PostgreSQL 15]
            │
            └──► [Relés DERP do Tailscale - públicos gratuitos]

Componentes:

• Contabo Cloud VPS 4 Nuremberg (4 vCPU, 8 GB RAM, 100 GB SSD, €5.50/mês) - veja a nossa análise do Contabo 2026 e o tutorial de configuração passo a passo para preparar o VPS.
• Headscale 0.24 como coordenador.
• PostgreSQL 15 como backend (vs SQLite padrão, mais robusto à medida que o número de nós cresce).
• Caddy 2 como proxy reverso com TLS automático do Let's Encrypt - o Headscale precisa de HTTPS, os clientes oficiais exigem-no.
• OIDC via Authentik (também auto-hospedado, mas Auth0 ou Keycloak também funcionam).
• Relés DERP públicos do Tailscale para travessia NAT - gratuitos, não há necessidade de auto-hospedar DERP a menos que tenha restrições de paranoia específicas.

Instalação passo a passo no Contabo

Tempo de configuração num VPS recém-provisionado: cerca de 90 minutos se seguir os passos sem hesitação. Assumiremos Debian 12 (o padrão do Contabo).

1. Preparação do sistema

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

2. Criar a base de dados PostgreSQL do Headscale

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

3. Instalar o Headscale

O pacote.deb oficial é o caminho mais limpo. Última versão: github.com/juanfont/headscale/releases.

HS_VERSION="0.29.5"
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. Configuração do Headscale

Os valores abaixo são para o Headscale 0.29 (outubro de 2026). Para o ficheiro completo adaptado à sua instalação (Docker ou .deb, Caddy, nginx ou TLS integrado, SQLite como recomenda o projeto), use o nosso gerador de config Headscale.

Edite /etc/headscale/config.yaml. As configurações mínimas necessárias:

server_url: https://headscale.seu-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
    pass: COLOQUE_UMA_SENHA_FORTE_AQUI

derp:
  server:
    enabled: false
  urls:
    - https://controlplane.tailscale.com/derpmap/default

prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48

dns:
  magic_dns: true
  base_domain: ts.seu-dominio.com

policy:
  mode: file
  path: /etc/headscale/acl.json

oidc:
  issuer: https://auth.seu-dominio.com/application/o/headscale/
  client_id: headscale
  client_secret: OIDC_SECRET_AQUI
  scope: ["openid", "profile", "email"]

Pontos críticos:

• server_url deve ser HTTPS. Os clientes oficiais do Tailscale recusam-se a falar HTTP simples.
• prefixes.v4: 100.64.0.0/10 é o intervalo CGNAT que o Tailscale usa por padrão. Não altere a menos que saiba o que está a fazer.
• oidc: opcional, mas fortemente recomendado em produção. Sem isso, recai para headscale users create e chaves pré-partilhadas.

5. Caddy como proxy reverso

/etc/caddy/Caddyfile:

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

Recarregar: systemctl reload caddy. O Caddy obtém automaticamente o certificado Let's Encrypt. Verifique se a cadeia é válida antes de prosseguir - os clientes oficiais do Tailscale recusam auto-assinados.

6. Iniciar o Headscale

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

Deverá ver logs de inicialização, depois "Listening on 127.0.0.1:8080".

7. Criar um primeiro utilizador e uma chave de pré-autenticação

headscale users create eric
headscale users list   # numeric ID of eric, e.g. 1
headscale preauthkeys create --user 1 --reusable --expiration 24h

A saída fornece uma chave tskey-auth-xxxxxxxxxxxx. Anote-a.

8. Conectar um cliente Tailscale

Num cliente Linux com o cliente oficial Tailscale instalado:

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

O nó aparece em headscale nodes list. A partir daí, pode obter o seu IP 100.x.x.x e começar a usá-lo.

Para iOS/Android: instale a aplicação oficial do Tailscale, configurações → servidor de login personalizado → insira o URL do seu Headscale. Toque em "Sign in", será redirecionado para o seu fornecedor OIDC.

Configuração crítica de ACL

As ACLs são onde o Headscale mostra que é realmente "compatível com Tailscale". O ficheiro JSON aceita a mesma sintaxe que as ACLs Premium do Tailscale.

Exemplo de produção (equipa de 5 utilizadores com segregação 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"]
  }
}

Recarregue após cada edição: headscale acls reload. O Headscale valida o JSON antes de aplicar, por isso um erro de sintaxe nunca quebra a malha de produção.

Armadilhas de produção que ninguém menciona

Aqui estão quatro armadilhas a antecipar ao operar o Headscale:

1. Esgotamento da pool de conexões do PostgreSQL. O Headscale limita as suas conexões PostgreSQL (database.postgres.max_open_conns e max_idle_conns). Numa malha em que muitos nós se reconectam com frequência (pense em roaming Wi-Fi em telemóveis), uma pool demasiado pequena torna-se um gargalo. Verifique os valores padrão na configuração de exemplo da sua versão e aumente-os se os logs mostrarem conexões em espera.

2. Os relés públicos DERP do Tailscale podem estar longe de alguns dos seus nós. Quando o tráfego é retransmitido por uma região distante, a latência sobe. Solução: auto-hospede um relé DERP num VPS na região. O Headscale lida com isso de forma transparente - veja os documentos oficiais de configuração do DERP.

3. Backup do PostgreSQL é obrigatório e subestimado. O Headscale armazena tudo no PostgreSQL: nós, chaves públicas, estado de ACL, mapeamentos OIDC. Perder a BD é perder toda a malha. Configure pg_dump diário + backup automatizado para um armazenamento de objetos compatível com S3 (por ex. Hetzner Object Storage, ~€1/mês) e teste a sua restauração regularmente.

4. Atualizações binárias do Headscale são suaves, mas mudanças de quebra acontecem entre versões menores. Leia o CHANGELOG antes de atualizar de 0.23 para 0.24. A equipa de desenvolvimento é responsiva no GitHub, mas o Headscale está em desenvolvimento ativo - conte com elas em cada atualização.

Custos reais ao longo de 36 meses - Headscale vs Tailscale Premium

A matemática para 10 utilizadores, 25 nós, com suposições cautelosas:

O Headscale ganha por ~€2,230 ao longo de 36 meses com 10 utilizadores. Não é enorme, mas é real - e a diferença aumenta linearmente com o tamanho da equipa. Com 20 utilizadores, está a poupar ~€8,000/3 anos. Com 50 utilizadores, é dinheiro sério.

Se o seu tempo vale mais de €100/h, essa diferença diminui rapidamente. Se vale menos de €50/h (júnior, projeto paralelo, aprendizagem), o Headscale ganha facilmente.

Veredicto - quando implementar o Headscale em 2026

Implemente o Headscale se:

• Tem uma restrição de soberania / GDPR / sem transferência para os EUA
• A sua equipa tem 10+ utilizadores com horizonte de 12+ meses
• Tem um administrador de sistemas interno ou instinto de administrador de sistemas
• O Tailscale Premium parece caro, mas o WireGuard bruto parece demasiado primitivo

Mantenha-se no Tailscale Premium se:

• O seu tempo vale mais de €100/h
• Sem restrição de conformidade específica
• Prefere gastar esses 2-3 dias no seu produto

Mantenha-se no WireGuard bruto se:

• Está abaixo de 5 nós, configuração simples, em modo de aprendizagem
• Hub-and-spoke atende a todos os seus casos de uso

O Headscale é a resposta mais subestimada no ecossistema de VPN self-hosted em 2026. Faz a maior parte do trabalho do Tailscale, num VPS Contabo a €5.50/mês, com total soberania de dados. Se preferir um fornecedor dos EUA com 30 dias de reembolso, o VPS Basic da Ultahost custa 5,52 $ por mês em 24 meses (1 GB de RAM, IPv4 dedicado, lido a 21 de outubro de 2026), suficiente para um servidor Headscale de uma pequena equipa. O preço são 2-3 dias de configuração e um reflexo de administrador de sistemas.

Para ter os comandos à mão: a nossa Tailscale & Headscale Cheat Sheet gratuita (PDF de 4 páginas em inglês, download direto, sem registo) reúne status e ping, exit node, subnet router, Serve e Funnel, a configuração do Headscale, utilizadores, chaves e ACL, e as causas de falha habituais. Descarregar a ficha.

Indo mais além

• Headscale vs WireGuard: o túnel e o servidor que distribui as chaves - o que o WireGuard simples deixa por sua conta, e o que a documentação do Headscale diz que ele não é
• Tailscale vs WireGuard self-host: qual em 2026
• Self-host VPN no Contabo: guia completo do WireGuard 2026
• Configuração passo a passo do VPS Contabo para VPN 2026
• Monitorização de VPN VPS com Prometheus + Grafana
• Análise do Contabo 2026
• Calculadora de custos de VPN self-hosted - insira o número de utilizadores e a taxa horária para ver se o Headscale, Tailscale ou WireGuard bruto vence em TCO
• Comparador interativo de VPS - compare Contabo, Hetzner e OVH por latência, RAM e preços reais de 24 meses antes de escolher o seu host para Headscale

Fontes e referências:

• Headscale - código fonte e documentação oficial
• Site de documentação do Headscale
• Referência de sintaxe de ACL do Tailscale
• Guia de configuração do servidor DERP

Publicado em 2026-06-05. Guia baseado na documentação oficial do Headscale, não numa implementação de produção nossa. Custos de maio de 2026 do Contabo e Tailscale - verifique antes de decidir. O desempenho real e as economias dependem do tamanho da equipa e da infraestrutura existente.

Lembrete: Headscale, Tailscale e hospedagem própria de VPN são perfeitamente legais na UE, EUA, Canadá. A VPNSmith publica este conteúdo para fins educacionais.