Infraestrutura
Headscale self-hosted conecta sua rede em uma VPS
Instale Headscale self-hosted em VPS com HTTPS, clientes WireGuard, rotas privadas, DNS, backups e segurança para operar sua rede em produção estável.
Resposta direta
O Headscale self-hosted pode ser hospedado em uma VPS pequena para coordenar clientes Tailscale que formam uma rede privada baseada em WireGuard. Para um laboratório ou equipe reduzida, 1 vCPU, 1 GB de RAM e 10 GB de SSD costumam oferecer margem suficiente, desde que a máquina tenha endereço público, DNS e HTTPS. O Headscale gerencia identidade, chaves, rotas e políticas, mas o tráfego entre os dispositivos tenta seguir diretamente de um cliente ao outro. A implementação precisa incluir certificado TLS válido, firewall restritivo, backup do banco de dados e teste de restauração. Também é necessário conferir a compatibilidade dos aplicativos Tailscale com um servidor de controle personalizado, principalmente em celulares e desktops, antes de adotar a solução em produção.
Resumo rápido
- O Headscale substitui o servidor de coordenação, não o protocolo WireGuard usado pelos clientes Tailscale.
- Uma VPS com 1 vCPU e 1 GB de RAM atende laboratórios e redes pequenas; 2 vCPUs e 2 GB oferecem folga para métricas, proxy e mais dispositivos.
- O endpoint público deve usar HTTPS válido na porta 443, com DNS apontando para o endereço da VPS.
- Chaves de pré-autorização devem ter validade curta, uso único e armazenamento fora de scripts e repositórios.
- Subnet routers anunciam redes como
10.20.0.0/16; exit nodes encaminham tráfego de internet e exigem capacidade de banda maior. - SQLite simplifica ambientes pequenos, mas precisa de backup consistente junto com configuração, chave Noise e política de acesso.
- ACLs devem separar administradores, servidores, notebooks e dispositivos de automação, liberando apenas portas necessárias.
A escolha da infraestrutura depende mais da função do nó do que do número bruto de clientes. Um servidor de coordenação para 20 notebooks consome poucos recursos, pois não deveria transportar todo o tráfego. Já uma VPS que também atua como exit node pode transferir centenas de gigabytes, manter muitas conexões e exigir 2 ou 4 vCPUs. Quem ainda está decidindo entre uma malha WireGuard e um gateway convencional pode comparar essa arquitetura com uma VPS para VPN privada no Brasil. O modelo operacional, os pontos de falha e o consumo de banda são diferentes.
O que o Headscale controla na rede WireGuard
Plano de controle e tráfego entre os dispositivos
O Headscale é uma implementação aberta do servidor de coordenação utilizado por clientes Tailscale. Ele cadastra dispositivos, distribui informações necessárias à descoberta dos pares, administra rotas e aplica políticas. As interfaces dos clientes continuam usando WireGuard para criptografar os pacotes. Essa distinção evita um erro comum: tratar a VPS do Headscale como se ela fosse, obrigatoriamente, o concentrador de todo o tráfego privado.
Considere três máquinas cadastradas: um notebook em Recife, um servidor de aplicação em São Paulo e um NAS no escritório. O Headscale informa aos clientes quais endereços e chaves pertencem a cada nó. Depois disso, notebook e servidor tentam estabelecer uma conexão direta por UDP. Se a travessia de NAT não funcionar, um relay DERP compatível pode intermediar os pacotes. A criptografia continua de ponta a ponta, mas o relay acrescenta latência e passa a consumir banda.
Esse comportamento muda o dimensionamento. Dez servidores trocando backups de 50 GB diretamente não transferem esses 500 GB pela VPS de coordenação. Porém, o consumo pode passar por um relay quando o caminho direto falha. Se a própria VPS também for configurada como exit node, o tráfego de navegação dos clientes passa por ela e a franquia de transferência torna-se decisiva.
Headscale não é um clone completo do painel Tailscale
O Headscale cobre o núcleo de coordenação, mas não reproduz automaticamente todos os recursos, integrações, fluxos de login e telas administrativas do serviço gerenciado. A experiência também varia conforme o sistema operacional. Em Linux, informar uma URL de login personalizada é direto. Aplicativos para Windows, macOS, Android e iOS podem exigir passos específicos, opções do cliente ou perfis de configuração, conforme a versão.
Há três cenários nos quais essa diferença fica evidente. Uma equipe que usa login corporativo pode precisar integrar um provedor OpenID Connect e revisar o fluxo de autorização. Um laboratório doméstico pode preferir usuários locais e chaves descartáveis. Uma empresa com notebooks gerenciados precisa validar atualização, revogação e recuperação antes de migrar todos os usuários. Headscale oferece controle sobre o plano de coordenação, mas esse controle vem acompanhado de responsabilidade operacional.
Como dimensionar a VPS e desenhar a arquitetura
CPU, memória, disco e rede
O consumo básico do Headscale é modesto. Para até 25 dispositivos, uma referência inicial razoável é 1 vCPU, 1 GB de RAM e 10 GB de SSD. Uma instalação para 25 a 150 dispositivos pode começar com 2 vCPUs, 2 GB de RAM e 20 GB de SSD, principalmente quando a mesma VPS executa Caddy, coleta de métricas e agentes de monitoramento. Esses números são pontos de partida, não limites comprovados por benchmark. Quantidade de registros, frequência de conexão, observabilidade e serviços adicionais mudam o resultado.
Disco NVMe raramente é o principal fator em uma implantação pequena. O banco de coordenação registra estado e metadados, mas não recebe o volume de escrita de um banco transacional de aplicação. Latência de rede, disponibilidade do endereço público e estabilidade do provedor tendem a pesar mais. SSD ou NVMe com espaço livre, monitoramento e backup é melhor do que armazenamento rápido sem rotina de restauração.
A tabela organiza três perfis sem atrelar a recomendação a um provedor específico:
| Perfil | Dispositivos de referência | CPU e RAM iniciais | Disco | Rede e função indicada |
|---|---|---|---|---|
| Laboratório pessoal | Até 25 | 1 vCPU, 1 GB | 10 GB SSD | Coordenação, DNS e proxy HTTPS |
| Equipe pequena | 25 a 150 | 2 vCPUs, 2 GB | 20 GB SSD | Coordenação, métricas e subnet routers externos |
| Coordenação mais exit node | Até 150, conforme tráfego | 2 a 4 vCPUs, 2 a 4 GB | 20 a 40 GB SSD | Porta de 1 Gbps e franquia compatível com o uso |
| Operação crítica | Centenas, após teste de carga | 4 vCPUs, 4 GB ou mais | 40 GB com backup externo | Monitoramento, redundância planejada e recuperação documentada |
VPS tradicional ou Cloud Server
Uma VPS tradicional pode hospedar o Headscale sem dificuldade quando os recursos são previsíveis e a indisponibilidade durante manutenção é aceitável. Um Cloud Server pode facilitar redimensionamento, troca de endereço, automação e integração com snapshots, mas isso não cria alta disponibilidade por si só. Se banco, chave Noise e DNS dependem de uma única instância, ela continua sendo um ponto único de falha.
Localidade também exige contexto. Hospedar no Brasil reduz a latência até o plano de controle para usuários brasileiros, embora conexões diretas entre pares não dependam da VPS depois de estabelecidas. IPv6 público ajuda em algumas topologias e reduz dependência de NAT, desde que clientes, firewall e DNS estejam configurados corretamente. O planejamento descrito no conteúdo sobre VPS com IPv6 no Brasil ajuda a avaliar dual stack sem assumir que IPv6, sozinho, resolverá a conectividade entre todos os pares.
Instalação do Headscale com HTTPS
Preparação do sistema e do serviço
Use uma distribuição com suporte ativo, como Debian estável ou Ubuntu LTS, e instale o pacote pelo método oficial documentado para a versão escolhida. Antes de iniciar, crie um registro DNS, por exemplo hs.exemplo.com, apontando para o IPv4 público e, se utilizado, para o IPv6. Sincronização de horário também é necessária, pois certificados e autenticação são sensíveis a relógios incorretos.
Uma preparação básica em Ubuntu pode começar assim:
sudo apt update
sudo apt upgrade -y
sudo timedatectl set-timezone America/Sao_Paulo
sudo systemctl enable --now systemd-timesyncd
Depois da instalação do pacote Headscale, mantenha o processo sob o systemd. O nome do pacote, repositório e formato da configuração podem mudar entre versões, então os comandos de instalação devem ser conferidos na documentação oficial antes da publicação ou execução. Para validar o serviço, use systemctl status headscale, consulte journalctl -u headscale e execute o validador de configuração disponibilizado pela versão instalada.
Configuração básica do Headscale
O arquivo costuma definir URL pública, endereço de escuta, banco, prefixos IP e DNS. Um modelo conceitual, que precisa ser comparado com o arquivo de exemplo da versão instalada, é:
server_url: https://hs.exemplo.com
listen_addr: 127.0.0.1:8080
metrics_listen_addr: 127.0.0.1:9090
database:
type: sqlite
sqlite:
path: /var/lib/headscale/db.sqlite
prefixes:
v4: 100.64.0.0/10
v6: fd7a:115c:a1e0::/48
dns:
magic_dns: true
base_domain: rede.exemplo.com
Escutar em 127.0.0.1:8080 impede acesso direto à aplicação pela internet. A porta de métricas também deve permanecer local ou ser liberada somente para o coletor. Não publique o banco, a chave Noise ou arquivos de configuração por HTTP.
Proxy reverso e certificado TLS
Caddy oferece uma configuração curta e automatiza certificados quando o DNS já aponta para a VPS:
hs.exemplo.com {
reverse_proxy 127.0.0.1:8080
}
Nginx também funciona, mas precisa encaminhar corretamente HTTP/2, cabeçalhos e conexões exigidas pelo protocolo. No firewall, permita SSH apenas a partir de endereços administrativos quando possível, além de TCP 80 para emissão ou redirecionamento de certificado e TCP 443 para os clientes. A porta interna 8080 não deve ser aberta publicamente.
Se o objetivo for somente alcançar uma aplicação web sem formar uma malha entre dispositivos, uma solução de túnel pode ser mais simples. O artigo sobre VPS para Cloudflare Tunnel e acesso seguro explica essa alternativa. Headscale faz mais sentido quando servidores, notebooks e sub-redes precisam conversar como participantes de uma rede privada persistente.
Como conectar servidores, notebooks e redes privadas
Usuários, chaves temporárias e registro dos clientes
Após iniciar o serviço, crie uma identidade administrativa ou um usuário para cada pessoa, equipe ou finalidade. Os nomes e a sintaxe exata dos comandos mudaram em versões recentes, por isso confirme as opções com headscale users --help e headscale preauthkeys --help. Um fluxo típico cria o usuário e emite uma chave curta:
sudo headscale users create equipe
sudo headscale preauthkeys create --user equipe --expiration 24h
A chave resultante não deve entrar em histórico compartilhado, imagem de máquina, repositório Git ou documentação. No cliente Linux, ela pode ser lida de forma interativa e mantida apenas na sessão atual:
read -rsp "Chave temporaria: " HEADSCALE_AUTH_KEY
sudo tailscale up \
--login-server=https://hs.exemplo.com \
--auth-key="$HEADSCALE_AUTH_KEY"
unset HEADSCALE_AUTH_KEY
Para um notebook individual, prefira chave de uso único com validade curta. Em uma esteira de provisionamento, use um cofre de segredos e revogue a credencial ao final. Em servidores duradouros, aplique tags controladas por ACL em vez de compartilhar uma conta administrativa entre várias máquinas.
Subnet router, exit node e MagicDNS
Um subnet router permite alcançar equipamentos que não executam Tailscale. Imagine uma filial com a rede 10.20.0.0/16. Um Linux dentro dessa rede pode anunciar a rota:
sudo sysctl -w net.ipv4.ip_forward=1
sudo tailscale up \
--login-server=https://hs.exemplo.com \
--advertise-routes=10.20.0.0/16
A rota precisa ser revisada e aprovada no Headscale. Consulte headscale routes list e o subcomando de habilitação oferecido pela versão instalada. Antes da aprovação, confirme que 10.20.0.0/16 não entra em conflito com redes domésticas ou VPNs usadas pelos clientes. Conflitos com blocos comuns, como 192.168.0.0/24, produzem falhas difíceis de diagnosticar.
Um exit node é anunciado com --advertise-exit-node e passa a encaminhar o acesso externo dos clientes que o selecionarem. Nesse caso, dimensione banda, regras de NAT, responsabilidade sobre logs e localização do endereço de saída. MagicDNS simplifica nomes internos, como api.rede.exemplo.com, mas não substitui uma estratégia de DNS corporativo. Para resolver zonas privadas existentes, configure nameservers divididos e teste Linux, Windows e dispositivos móveis separadamente.
Segurança, ACLs, backups e observabilidade
Política de acesso com privilégio mínimo
Uma rede privada plana permite que qualquer dispositivo comprometido tente alcançar os demais. Separe notebooks, servidores, automações e administradores por usuários, grupos ou tags. Um desenvolvedor pode precisar de SSH no ambiente de homologação, mas não de acesso ao banco de produção. Um agente de monitoramento precisa consultar métricas em uma porta específica, sem permissão para abrir sessões administrativas.
Uma política ilustrativa em formato HuJSON pode associar operadores a servidores e liberar somente SSH:
{
"groups": {
"group:ops": ["operador"]
},
"tagOwners": {
"tag:servidor": ["group:ops"]
},
"acls": [
{
"action": "accept",
"src": ["group:ops"],
"dst": ["tag:servidor:22"]
}
]
}
A sintaxe deve ser validada contra a versão do Headscale. Comece com duas máquinas de teste, confirme conexões permitidas e bloqueadas e só depois aplique a política à rede inteira. Revogue dispositivos perdidos e remova chaves expiradas durante revisões periódicas.
Backup consistente e restauração testada
No ambiente com SQLite, copie o banco de forma consistente. Parar brevemente o serviço é a opção mais simples para redes pequenas. Outra possibilidade é usar o comando .backup do SQLite, evitando uma cópia parcial enquanto há escrita:
sudo sqlite3 /var/lib/headscale/db.sqlite \
".backup '/srv/backup/headscale.sqlite'"
sudo chmod 600 /srv/backup/headscale.sqlite
Inclua no backup o arquivo de configuração, a chave Noise, a política de ACL e as configurações do proxy. Criptografe a cópia e envie-a para outro servidor ou armazenamento de objetos. Um snapshot da mesma VPS ajuda contra erro operacional, mas não protege de exclusão da conta, falha regional ou credencial comprometida. Teste a restauração em uma instância isolada pelo menos a cada trimestre.
Logs, métricas e alertas
Monitore reinicializações, erros de banco, expiração de certificado, uso de disco e respostas HTTP do endpoint. Restrinja 127.0.0.1:9090 a um Prometheus local ou conecte o coletor pela própria rede privada. Três alertas iniciais são suficientes para evitar silêncio operacional: endpoint indisponível por cinco minutos, certificado com menos de 15 dias de validade e disco acima de 80%. Logs podem conter nomes de dispositivos e endereços IP, portanto defina retenção e acesso compatíveis com a política da organização.
Como diagnosticar conexão lenta ou dispositivo offline
Testes de conectividade e caminho direto
Comece pelas camadas mais simples. Confirme resolução de hs.exemplo.com, validade do certificado e acesso TCP à porta 443. No servidor, verifique systemctl status headscale, journalctl -u headscale --since -30min e os logs do proxy. No cliente, rode tailscale status e tailscale netcheck. Esses comandos ajudam a separar falha de autenticação, indisponibilidade do plano de controle e problema no caminho entre pares.
Um dispositivo cadastrado, mas offline, pode estar com relógio errado, chave revogada, URL de controle antiga ou bloqueio de DNS. Se dois servidores aparecem online, mas não trocam pacotes, revise a ACL e teste a porta do serviço, não apenas ICMP. Um banco PostgreSQL na porta 5432 pode estar bloqueado pelo firewall local mesmo quando o endereço WireGuard responde.
Para medir o caminho, faça três comparações. Teste a latência normal entre os nós, identifique no status se a conexão está direta ou usa relay e execute uma transferência controlada com iperf3. Um resultado de 400 Mbit/s em caminho direto e 40 Mbit/s via relay não prova defeito da VPS; pode indicar NAT restritivo, UDP bloqueado ou relay distante. Registre horário, sistemas, versões e direção do teste antes de alterar a infraestrutura.
MTU, NAT, UDP bloqueado e relay DERP
Páginas que começam a carregar e travam, SSH intermitente ou transferências que congelam podem indicar MTU inadequada. Teste pacotes com tamanho progressivo e considere encapsulamentos adicionais da rede local ou do provedor. Evite reduzir a MTU aleatoriamente em todos os clientes, pois isso mascara o diagnóstico e pode diminuir eficiência.
Em redes corporativas, hotéis e conexões móveis, UDP pode ser limitado. Os clientes então dependem de relay. O Headscale pode distribuir um mapa DERP, usar relays compatíveis e, conforme a versão e a arquitetura adotada, integrar um relay operado pela própria equipe. Não presuma que ativar um relay na mesma VPS resolverá tudo. Ele aumenta consumo de banda, superfície exposta e impacto de uma falha única.
Também verifique sobreposição de rotas. Um notebook conectado a uma rede local 10.20.0.0/16 não conseguirá distinguir essa LAN de uma sub-rede remota com o mesmo bloco sem uma estratégia adicional. Trocar a rede remota para um prefixo menos comum costuma ser mais previsível do que empilhar NAT. Documente os prefixos anunciados e mantenha apenas um subnet router ativo, ou dois com comportamento testado, para cada rota.
Recomendações por perfil
Desenvolvedor solo e laboratório
Para um desenvolvedor que deseja alcançar duas ou três VMs, um NAS e um notebook, comece com 1 vCPU, 1 GB de RAM e 10 GB de SSD. Use SQLite, Caddy e uma única URL HTTPS. Crie chaves de uso único com validade de uma hora ou 24 horas e mantenha o SSH público fechado depois que o acesso pela rede privada estiver validado. Um backup diário do banco e da configuração, copiado para fora da VPS, já cobre os principais riscos. Evite instalar painel administrativo, banco externo e relay próprio sem necessidade, pois cada componente adiciona manutenção. Faça primeiro um teste com um servidor e um notebook em redes distintas.
Equipe pequena
Para uma equipe de cinco a 30 pessoas, 2 vCPUs, 2 GB de RAM e 20 GB de SSD oferecem espaço para Headscale, proxy, métricas e logs moderados. Separe usuários humanos de identidades de automação. Aplique ACLs por função, use tags para servidores e mantenha subnet routers em máquinas próximas das redes anunciadas. Se houver autenticação por OpenID Connect, valide desligamento de contas, renovação de sessão e acesso emergencial antes de depender do fluxo. Monitore certificado, banco e espaço em disco. Um segundo administrador deve saber restaurar o serviço sem depender da conta ou do notebook de quem realizou a instalação inicial.
Produção com serviços críticos
Em produção, o requisito principal não é apenas aumentar CPU. Desenhe recuperação. Use 2 a 4 vCPUs, 4 GB de RAM e armazenamento persistente como ponto inicial quando houver centenas de dispositivos, métricas detalhadas ou funções adicionais, mas valide a capacidade com testes representativos. Mantenha backups criptografados, restauração ensaiada, DNS sob controle da equipe e documentação dos prefixos anunciados. Não coloque o único exit node, o único relay e o servidor de coordenação na mesma VPS sem aceitar explicitamente esse domínio de falha.
Se uma interrupção do plano de controle tiver impacto financeiro imediato, teste como os clientes existentes se comportam durante indisponibilidade e quanto tempo novas conexões podem esperar. Considere uma instância de recuperação preparada, sem assumir que dois processos Headscale apontados para arquivos SQLite copiados formam um cluster seguro. Alta disponibilidade exige suporte da arquitetura, consistência do banco, proteção das chaves e procedimento claro de mudança de DNS. Para qualquer perfil, a escolha do provedor deve considerar localidade, histórico operacional, rede, backup externo e suporte, não apenas quantidade anunciada de RAM.
Continue lendo
Perguntas frequentes
O Headscale substitui completamente o Tailscale?
O Headscale substitui principalmente o servidor de coordenação usado pelos clientes Tailscale, mas não reproduz necessariamente todo o serviço gerenciado, o painel, as integrações e os fluxos comerciais da Tailscale. Os clientes continuam criando túneis WireGuard e tentando conexões diretas entre os pares. Recursos como login corporativo, aplicativos móveis, políticas, DNS e relay precisam ser validados conforme a versão. Para laboratório e equipes técnicas, essa diferença pode ser aceitável. Para ambientes corporativos, convém testar cadastro, revogação, recuperação e atualização antes de migrar todos os dispositivos.
Quanta RAM uma VPS de Headscale precisa?
Uma instalação pequena, com até cerca de 25 dispositivos e sem serviços pesados adicionais, pode começar com 1 GB de RAM e 1 vCPU. Para equipes com dezenas de dispositivos, proxy HTTPS, métricas e logs, 2 GB de RAM e 2 vCPUs oferecem margem mais confortável. O Headscale não deveria transportar todo o tráfego entre os clientes, por isso o consumo do plano de controle costuma ser baixo. A necessidade cresce quando a VPS também funciona como exit node, relay, banco externo ou servidor de monitoramento. A capacidade final deve ser confirmada com métricas do ambiente real.
O tráfego privado passa pela VPS do Headscale?
Normalmente, o Headscale coordena os clientes, enquanto os dados tentam seguir diretamente entre os dispositivos por um túnel WireGuard. Se a conexão direta falhar por causa de NAT restritivo, firewall ou bloqueio de UDP, um relay DERP pode intermediar o tráfego. A VPS também transportará dados se for configurada como exit node ou se executar o relay utilizado pelos clientes. Essa distinção afeta custo, franquia de transferência e desempenho. Use `tailscale status` e `tailscale netcheck` para verificar se uma sessão está direta ou depende de relay antes de atribuir lentidão ao servidor de coordenação.
É obrigatório usar domínio e certificado HTTPS?
Para uma implantação segura e compatível com clientes em diferentes redes, use um domínio controlado pela equipe e um certificado TLS válido. O DNS deve apontar para a VPS, enquanto Caddy, Nginx ou outro proxy recebe conexões na porta 443 e encaminha para o Headscale em uma interface local. Certificados autoassinados aumentam a complexidade porque cada cliente precisa confiar manualmente na autoridade emissora. Também dificultam aplicativos móveis e processos automatizados. Mantenha renovação monitorada e gere alerta antes do vencimento, pois um certificado expirado pode impedir novos registros e reconexões ao plano de controle.
Como fazer backup de uma instalação Headscale?
O backup deve incluir banco de dados, configuração, chave Noise, política de ACL e arquivos do proxy reverso. Com SQLite, pare brevemente o serviço ou use o comando `.backup` do próprio SQLite para criar uma cópia consistente. Armazene o resultado de forma criptografada fora da VPS. Snapshots ajudam na recuperação rápida, mas não substituem uma cópia externa porque podem desaparecer junto com a conta ou a região. Faça uma restauração trimestral em ambiente isolado e confirme se usuários, dispositivos, rotas e políticas reaparecem. Um backup nunca testado é apenas uma expectativa de recuperação.
Headscale funciona com Windows, macOS, Android e iOS?
Os clientes Tailscale existem para esses sistemas, mas a configuração de um servidor de controle personalizado não é idêntica em todas as plataformas. Linux costuma permitir a URL por linha de comando. Windows e macOS podem exigir opções específicas do aplicativo, comandos administrativos ou perfis gerenciados. Android e iOS merecem teste antecipado porque políticas das lojas e mudanças no cliente podem afetar o fluxo. Antes de uma adoção ampla, valide instalação, login, reconexão, atualização e revogação em cada sistema usado pela equipe. Consulte a documentação oficial do Headscale e do cliente para a versão instalada.
Fontes consultadas
- Headscale Documentation · coletado em 15/10/2026
- Headscale GitHub Repository · coletado em 15/10/2026
- Tailscale Documentation, Custom Coordination Server · coletado em 15/10/2026
- Caddy Documentation, Reverse Proxy · coletado em 15/10/2026