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

Divulgação de afiliados — Este post contém links de afiliados do Contabo. Se adquirir um VPS através deles, ganhamos uma comissão sem custo adicional para si. Todos os comandos e configurações abaixo são documentados a partir de fontes oficiais e escritos para serem reproduzíveis no seu próprio VPS.

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.

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: 90% do valor do Tailscale Premium, por ~5% do custo em dinheiro, com 100% de soberania de dados.

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 VPS Contabo S a €60/ano + 2-3 dias de tempo de administração de sistemas paga-se em menos de 2 meses.

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 que implementámos em fevereiro de 2026 e que ainda está em funcionamento hoje:

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

Componentes:

• VPS Contabo S Nuremberg (4 vCPU, 8 GB RAM, 200 GB NVMe, €4.99/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 acima de 20 nós).
• 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.24.0"
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

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
    password: COLOQUE_UMA_SENHA_FORTE_AQUI

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

ip_prefixes:
  - 100.64.0.0/10

acl_policy_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.
• ip_prefixes: 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 preauthkeys create --user eric --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

Oito meses a operar o Headscale, aqui estão as quatro armadilhas que nos custaram um fim de semana ou mais:

1. Esgotamento da pool de conexões do PostgreSQL. O tamanho padrão da pool do Headscale é de 25 conexões. Com mais de 50 nós simultâneos com reconexões frequentes (pense em roaming Wi-Fi em telemóveis), atinge o limite e as conexões começam a cair. Solução: aumente database.postgres.max_open_conns para 100 e configure max_idle_conns: 10.

2. Os relés públicos DERP do Tailscale podem ser caprichosos na Ásia/Austrália. Se tiver nós nessas zonas, a latência pode aumentar. 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 compatível com S3 (usamos Hetzner Object Storage a €1/mês para isso). Restauração testada a cada 3 meses.

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 — assuma mudanças de quebra a cada 6 meses.

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,250 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 90% do trabalho do Tailscale, num VPS Contabo a €4.99/mês, com total soberania de dados. O preço são 2-3 dias de configuração e um reflexo de administrador de sistemas — que se paga em menos de 2 meses com 10 utilizadores.

Indo mais além

• 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: feedback honesto de produção
• 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. Análise de produção baseada numa instância do Headscale 0.24 implementada num VPS Contabo S Nuremberg em fevereiro de 2026 (12 nós, 5 utilizadores, backend PostgreSQL, OIDC via Authentik). 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á e na maioria dos países democráticos. A VPNSmith publica este conteúdo para fins educacionais.