Headscale na VPS: servidor de controle Tailscale próprio
O controle da rede Tailscale no seu servidor: pacote oficial, HTTPS, usuários e chaves, clientes com --login-server, política de acesso, backup e atualização sem pular versão.
Por Redação Eleven Host · @robson.direitodigital · 22 de novembro de 2026 · 10 min de leitura

Capa da Redação Eleven Host para o guia: Headscale na VPS: servidor de controle Tailscale próprio Arte: Eleven Host
Headscale na VPS é instalar, num servidor seu, uma implementação de código aberto do servidor de controle do Tailscale: o serviço que troca as chaves das máquinas, distribui os endereços da rede privada e guarda as regras de acesso.
Atualizado em 22/11/2026. Confira cada comando antes de usar e teste primeiro numa máquina sem dados importantes.
Em 22/11/2026, a versão estável do Headscale era a v0.29.7, de 30/10/2026, e o repositório juanfont/headscale estava ativo, sob licença BSD-3-Clause, sem alerta de segurança publicado na página do projeto. O README avisa que o Headscale não tem ligação com a Tailscale Inc.
O que o servidor de controle faz
Numa rede Tailscale, cada máquina roda o cliente Tailscale, e um servidor central coordena a rede. Pelo README do projeto, esse servidor de controle troca as chaves públicas WireGuard entre os nós, atribui o IP de cada cliente e cuida das rotas anunciadas e do compartilhamento. O Headscale assume esse papel no seu servidor; nas máquinas, o cliente continua sendo o app Tailscale.
Quando duas máquinas não conseguem falar direto, o tráfego passa por um relay chamado DERP. Pela documentação, o Headscale usa por padrão os servidores DERP públicos da Tailscale. Há um DERP embutido, ligado com derp.server.enabled: true e STUN na porta 3478/UDP; para usar só o seu, a lista urls precisa ficar vazia.
Se você ainda não usa o Tailscale, comece por Tailscale na VPS: acesso privado ao servidor e painéis. Este é o passo seguinte para quem quer o controle da rede no próprio servidor. Também há um artigo na base sobre outro caminho, "WireGuard na VPS: como criar sua própria VPN".
Para quem serve e quando não vale
O README define um escopo estreito: uma única tailnet, pensada para uso pessoal ou para uma pequena organização de código aberto. O FAQ cita entusiastas, laboratórios e pequenos projetos de código aberto. Sobre tamanho, ele diz que o Headscale provavelmente aguenta centenas de dispositivos numa rede estável, mas sofre quando muitos nós mudam com frequência, porque recalcula o mapa inteiro da rede a cada mudança.
A página de recursos lista suporte às funções base do Tailscale: MagicDNS, split DNS, subnet routers, exit nodes, Taildrop, Tailscale SSH, ACLs e grants, chaves pré-autenticadas e login por OIDC. Uma limitação aparece de forma explícita: grupos do OIDC não entram nas ACLs.
Nosso conselho: o Headscale faz sentido para uma pequena empresa ou um desenvolvedor com 1 a 3 servidores que quer a lista de máquinas e as regras sob o próprio controle. Se você precisa de várias tailnets, tem muitas máquinas entrando e saindo ou não quer cuidar de atualização e backup de mais um serviço, o controle hospedado pela própria Tailscale continua sendo o caminho. O que é uma VPS e como escolher uma está em O que é servidor VPS: guia simples para iniciantes.
Uma casa para o servidor de controle
O Headscale fica instalado numa máquina que você mesmo administra.
Servidor virtual privado administrado por você, a VPS também é vendida pela Eleven Host. VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver planos de VPS
Requisitos e portas
A página de requisitos pede um servidor com IP público (IPv4 e IPv6 públicos são recomendados), HTTPS na porta 443, um Linux ou BSD razoavelmente moderno e um usuário local dedicado. As portas listadas são estas:
- 443/TCP, pública: HTTPS para os clientes Tailscale;
- 80/TCP, pública: só se usar o Let's Encrypt embutido com o desafio HTTP-01;
- 3478/UDP, pública: só com o DERP embutido;
- 50443/TCP: gRPC para controle remoto, só se usar;
- 9090/TCP, não pública: métricas e debug.
Mantenha a 9090 e a 50443 fora da internet; no arquivo de exemplo, as duas já escutam em 127.0.0.1. O FAQ informa que as imagens de contêiner são publicadas, mas rodar o Headscale em Docker não tem suporte oficial; por isso a instalação descrita usa o pacote .deb.
Passo 1: o nome do servidor
Os clientes chegam ao Headscale por um endereço com HTTPS, como https://headscale.suaempresa.com.br. Crie no DNS um registro A (e AAAA, se a VPS tiver IPv6) desse subdomínio apontando para o IP do servidor, antes de pedir o certificado.
A documentação da comunidade avisa que rodar o Headscale atrás do proxy ou do túnel da Cloudflare não é suportado, porque eles não deixam passar as conexões que o protocolo do Tailscale usa. Nosso conselho: se o DNS do domínio estiver num serviço com proxy, deixe esse registro só como DNS.
Passo 2: instalar o pacote .deb
O pacote oficial atende Ubuntu 22.04 ou mais novo e Debian 12 ou mais novo. Um exemplo de comando com a release v0.29.7, a estável em 22/11/2026 (sem o "v" na versão; troque amd64 por arm64 se for o caso, e instale o wget antes se ele não existir):
sudo apt install wget
HEADSCALE_VERSION="0.29.7"
HEADSCALE_ARCH="amd64"
wget --output-document=headscale.deb "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
sudo apt install ./headscale.deb
Pela documentação, a configuração fica em /etc/headscale/config.yaml; o pacote traz um exemplo comentado em /usr/share/doc/headscale/examples/config-example.yaml e instala um serviço que roda como o usuário headscale, com permissão para abrir portas baixas, como a 443. Confira se ele sobe no boot com systemctl is-enabled headscale e, se preciso, rode sudo systemctl enable headscale.
Passo 3: o config.yaml
Abra o arquivo com sudo nano /etc/headscale/config.yaml. Use como referência o exemplo da mesma versão instalada: a documentação avisa que o do branch principal pode trazer mudanças ainda não lançadas. As chaves que mais pedem atenção:
server_url: o endereço público que os clientes usam; o padrão,http://127.0.0.1:8080, aponta para a própria máquina;listen_addr: onde o serviço escuta; o padrão é127.0.0.1:8080;prefixes: as faixas da rede, por padrão100.64.0.0/10efd7a:115c:a1e0::/48;dns.base_domain: o sufixo do MagicDNS; cada máquina virahostname.base_domain, e esse domínio tem de ser diferente do domínio doserver_url;database: SQLite em/var/lib/headscale/db.sqlite, o banco que o FAQ recomenda.
Para o HTTPS há dois caminhos. No primeiro, o Headscale pede sozinho o certificado ao Let's Encrypt. Um exemplo de trecho, com o desafio HTTP-01 (que exige a porta 80 aberta); nos blocos aninhados do arquivo, mantenha 2 espaços por nível:
server_url: https://headscale.suaempresa.com.br
listen_addr: 0.0.0.0:443
tls_letsencrypt_hostname: headscale.suaempresa.com.br
tls_letsencrypt_challenge_type: HTTP-01
Pela documentação, o certificado vale 3 meses e a renovação é tentada quando faltam 30 dias ou menos, sem linha no log quando dá certo; confira a validade de vez em quando no navegador ou com openssl s_client.
No segundo caminho, um proxy reverso cuida do certificado. A página sobre isso é da comunidade, sem verificação dos desenvolvedores, e o FAQ diz que os mantenedores não usam proxy. Nesse caso, o server_url continua com https, o Headscale fica em 127.0.0.1:8080, tls_cert_path e tls_key_path ficam vazios e o proxy precisa repassar WebSocket. No nginx, com um bloco map que define $connection_upgrade a partir de $http_upgrade, as linhas-chave do exemplo são proxy_http_version 1.1;, proxy_set_header Upgrade $http_upgrade;, proxy_set_header Connection $connection_upgrade; e proxy_buffering off;.
Depois de salvar, valide e reinicie:
sudo headscale configtest
sudo systemctl restart headscale
sudo systemctl status headscale
Passo 4: usuário e chave de pré-autenticação
Por padrão, só root e o usuário headscale falam com o serviço pelo socket local, por isso os comandos usam sudo. Crie um usuário e veja o ID dele na lista, porque a chave pede o ID, não o nome:
sudo headscale users create equipe
sudo headscale users list
sudo headscale preauthkeys create --user ID-DO-USUARIO
Pela documentação, a chave vale 1 hora e serve uma vez só por padrão. As opções mudam entre versões: confira com sudo headscale preauthkeys --help. Trate a chave como senha: não a cole em chat nem em repositório.
Passo 5: conectar as máquinas
Numa máquina Linux com o Tailscale instalado, use a chave:
sudo tailscale up --login-server https://headscale.suaempresa.com.br --authkey CHAVE-GERADA
Sem chave, rode só com --login-server. O cliente mostra uma página de registro com um Auth ID, que você aprova no servidor com sudo headscale auth register --user equipe --auth-id AUTH-ID.
Nos outros sistemas, a página da Tailscale sobre servidor de coordenação próprio diz que, no Windows, a interface não aceita outro servidor: use a linha de comando ou o valor de registro LoginURL. No iOS e no Android, a opção de servidor personalizado fica nas configurações do app. As notas da v0.29.7 dizem que ela corrige várias falhas, algumas de negação de serviço, e recomendam atualizar também o cliente Tailscale para a v1.104.4 ou mais nova nos nós, principalmente com Tailscale SSH; a versão mínima suportada é a v1.80.0.
Passo 6: regras de acesso
Sem política, o Headscale libera o tráfego entre todas as máquinas. Para restringir, aponte policy.path para um arquivo HuJSON, no mesmo formato da política do Tailscale, e recarregue com sudo systemctl reload headscale; o resultado sai no log. O exemplo mínimo da documentação, {"grants": []}, bloqueia tudo: comece por ele só se for escrever as permissões logo em seguida.
Passo 7: backup e atualização
Na instalação pelo pacote, a documentação lista o que guardar: /etc/headscale e a pasta /var/lib/headscale, onde ficam o banco e as chaves privadas. Um exemplo de comando, com o serviço parado:
sudo systemctl stop headscale
TIMESTAMP=$(date +%Y%m%d%H%M%S)
sudo cp -aR /etc/headscale /etc/headscale.backup-$TIMESTAMP
sudo cp -aR /var/lib/headscale /var/lib/headscale.backup-$TIMESTAMP
sudo systemctl start headscale
Uma cópia que fica só na VPS some junto com ela: leve-a para fora, por exemplo com Duplicati na VPS: backup do servidor com painel web.
Para atualizar, a documentação manda ler as notas da release, parar o serviço, fazer o backup, instalar a versão nova pelo mesmo método, comparar o config com o exemplo novo e iniciar. Ela pede para subir uma versão menor por vez, sem pular (por exemplo, 0.26.0, depois 0.27.1, depois 0.28.0), sempre no último patch de cada uma. A atualização roda migrações no banco, e por isso a documentação recomenda fortemente o backup.
Checklist do Headscale na VPS
- subdomínio apontando para o servidor, sem proxy da Cloudflare;
- pacote .deb da v0.29.7 ou mais nova;
- server_url com HTTPS e base_domain diferente dele;
- 9090 e 50443 fora da internet;
- configtest sem erro antes de reiniciar;
- chaves de pré-autenticação tratadas como senha;
- clientes Tailscale atualizados;
- política de acesso definida;
- backup de /etc/headscale e /var/lib/headscale fora da VPS.
Um nome para o endereço do controle
Recomendamos escolher para o servidor de controle um nome curto, que a equipe consiga digitar sem erro.
O endereço headscale.suaempresa.com.br parte de um domínio próprio, que pode ser registrado na Eleven Host. Buscar domínio
Perguntas frequentes
O Headscale é da Tailscale?
Não. O README diz que o projeto não tem ligação com a Tailscale Inc., embora um dos mantenedores ativos seja funcionário dela.
Preciso trocar o app Tailscale das máquinas?
Não. O cliente continua sendo o Tailscale; muda o servidor de login, com --login-server ou a opção de servidor personalizado do app.
Dá para ter várias redes no mesmo Headscale?
O projeto foi desenhado para uma única tailnet. Para controlar quais máquinas se falam dentro dela, use a política de acesso.