Programação

ngrok: exponha seu localhost para o mundo em segundos

ngrok cria uma URL pública que aponta para o seu servidor local sem mexer no roteador. Entenda como funciona, para que serve e quando preferir alternativas.

Photo by Kirill Sh / Unsplash

Você acabou de terminar uma funcionalidade nova no seu projeto e quer testar o webhook do Stripe no servidor local. Ou quer mostrar uma demonstração do seu app para um cliente sem precisar fazer deploy. Ou simplesmente quer testar como o site fica no celular de um amigo que está em outro estado.

O problema é sempre o mesmo: o seu servidor está rodando em localhost, acessível apenas pelo seu próprio computador. Para qualquer pessoa de fora, ele simplesmente não existe.

É exatamente nesse momento que o ngrok entra em cena. E depois que você entende como ele funciona, você percebe o quanto ele simplifica uma classe inteira de problemas que antes exigiam configurações complicadas de roteador e firewall.

O que é o ngrok?

O ngrok é uma ferramenta que cria um túnel seguro entre os servidores dele (na internet) e o seu computador. O resultado é simples: você recebe uma URL pública, como https://abc123.ngrok.io, que qualquer pessoa no mundo pode acessar. Quando alguém visita essa URL, a requisição viaja até os servidores do ngrok e de lá é encaminhada, pelo túnel, para o seu localhost.

Para entender a mecânica, pense em um apartamento sem interfone. Se alguém chega na portaria, não tem como te avisar. O ngrok é como contratar um porteiro que fica na portaria, recebe as visitas e sobe até o seu apartamento para te avisar, funcionando como um intermediário entre o mundo externo e o seu servidor privado.

O processo todo acontece por iniciativa do seu computador: é ele quem abre a conexão com os servidores do ngrok, e não o contrário. Por isso, você não precisa abrir portas no roteador nem configurar nada na sua rede.

Como instalar e usar o ngrok

A instalação é rápida. O ngrok distribui um único arquivo executável para Linux, Mac e Windows.

No Linux (via snap):

sudo snap install ngrok

Ou via download direto:

# Faça o download do binário para Linux (64-bit)
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update \
  && sudo apt install ngrok

Depois de instalar, você precisa criar uma conta gratuita em ngrok.com e autenticar o seu cliente com o token da conta:

ngrok config add-authtoken SEU_TOKEN_AQUI

Com tudo configurado, expor um servidor local é um único comando. Se a sua aplicação está rodando na porta 3000:

ngrok http 3000

O terminal vai exibir algo assim:

Forwarding  https://abc123def456.ngrok-free.app -> http://localhost:3000

A URL https://abc123def456.ngrok-free.app agora está ativa e qualquer pessoa com acesso à internet pode usá-la para acessar o seu servidor local enquanto o ngrok estiver rodando.

Casos de uso reais

Testando webhooks

Este é, provavelmente, o caso de uso mais comum entre desenvolvedores. Serviços como Stripe (pagamentos), GitHub (eventos de repositório) ou Twilio (SMS e chamadas) precisam enviar notificações para uma URL acessível na internet quando algo acontece.

O problema é que, durante o desenvolvimento, o seu servidor está no localhost. Antes do ngrok, a solução era fazer deploy em um servidor de teste toda vez que você queria verificar se o webhook estava funcionando. Com o ngrok, você roda o servidor local e aponta o webhook para a URL do ngrok. Simples.

# Sobe o servidor local
npm run dev

# Em outro terminal, cria o túnel
ngrok http 3000

# Copia a URL gerada e coloca no painel do Stripe como URL de webhook
# Ex: https://abc123.ngrok-free.app/api/webhook/stripe

Demonstrações para clientes

Você acabou de implementar uma nova tela no sistema do cliente. Em vez de fazer um deploy de homologação ou gravar um vídeo, você levanta o ngrok durante a reunião e passa a URL. O cliente consegue interagir com a aplicação real, em tempo real, direto do navegador dele.

Testes em dispositivos físicos

Testar responsividade no celular usando as ferramentas de desenvolvedor do navegador é útil, mas não substitui o teste num dispositivo real. Com o ngrok, você sobe a URL no celular e testa a experiência real sem precisar que os dispositivos estejam na mesma rede.

Acesso remoto temporário ao seu computador

Precisa acessar um serviço rodando no seu computador de casa enquanto está no escritório? O ngrok resolve, para sessões temporárias. Para algo permanente, o Tailscale, que já abordamos em outros posts, é a solução mais adequada.

O painel de inspeção: um bônus que poucos conhecem

Um dos recursos mais úteis do ngrok é o painel de inspeção local, acessível pelo navegador enquanto o túnel está ativo:

http://127.0.0.1:4040

Nesse painel, você visualiza em tempo real cada requisição que chegou pelo túnel: os cabeçalhos HTTP, o corpo da requisição, o status da resposta e o tempo de processamento. Você também consegue repetir uma requisição com um único clique, o que é extremamente útil para debugar webhooks sem precisar acionar o evento externo repetidamente.

Alternativas ao ngrok

O ngrok não é o único serviço do tipo. Existem alternativas com propostas diferentes que valem conhecer:

Cloudflare Tunnel

O Cloudflare Tunnel (antigo Argo Tunnel) é a alternativa mais robusta para quem quer algo permanente e gratuito. A diferença principal em relação ao ngrok é que, em vez de receber uma URL gerada aleatoriamente, você pode vincular o túnel ao seu próprio domínio.

Se você tem o domínio meusite.com.br e quer que dev.meusite.com.br aponte para o seu servidor local, o Cloudflare Tunnel faz isso sem custo, usando a infraestrutura da Cloudflare como intermediário.

# Instala o cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/

# Autentica com sua conta Cloudflare
cloudflared tunnel login

# Cria o túnel
cloudflared tunnel create meu-tunel

# Sobe o túnel apontando para o localhost
cloudflared tunnel run --url http://localhost:3000 meu-tunel

localtunnel

O localtunnel é a opção mais simples para quem quer algo sem conta e sem instalação pesada. Funciona direto via npx:

npx localtunnel --port 3000

A URL gerada é temporária e o serviço é mais instável que o ngrok ou o Cloudflare Tunnel, mas para um teste rápido funciona bem.

bore

O bore é uma alternativa de código aberto, escrita em Rust, para quem quer rodar o próprio servidor de túnel. Em vez de depender da infraestrutura de uma empresa, você instala o bore num servidor VPS e usa o mesmo para criar os túneis.

# Instala via cargo (gerenciador de pacotes do Rust)
cargo install bore-cli

# Cria o túnel apontando para o servidor bore público
bore local 3000 --to bore.pub

Prós e contras de cada opção

Ferramenta	Gratuito	URL customizada	Estabilidade	Privacidade
ngrok (grátis)	Sim (com limites)	Não	Alta	Dados passam pelo ngrok
ngrok (pago)	Não	Sim	Alta	Dados passam pelo ngrok
Cloudflare Tunnel	Sim	Sim (com domínio)	Muito alta	Dados passam pela Cloudflare
localtunnel	Sim	Parcial	Baixa	Dados passam pelo serviço
bore (self-hosted)	Sim	Depende da VPS	Alta	Você controla o servidor

O ponto sobre privacidade merece atenção. Quando você usa o ngrok ou o Cloudflare Tunnel, o tráfego da sua aplicação passa pelos servidores dessas empresas antes de chegar ao seu computador. Para a maioria dos casos de desenvolvimento isso não é um problema, mas se você estiver expondo dados sensíveis de usuários reais, como num ambiente de homologação com dados reais de clientes, vale avaliar a alternativa self-hosted com o bore em uma VPS própria.

Quando não usar o ngrok

O ngrok resolve um problema temporário de conectividade. Ele não substitui uma infraestrutura de produção. Alguns casos em que ele não é a ferramenta certa:

Aplicações em produção: Se o seu servidor precisa ser acessível 24 horas por dia para usuários reais, você precisa de um servidor na nuvem (VPS) ou de um serviço de hosting dedicado, não de um túnel.
Acesso permanente entre seus próprios dispositivos: Para conectar o seu computador de casa com o notebook de trabalho ou criar uma rede privada com amigos para jogos, o Tailscale é a solução correta. Como explicamos em detalhes no post sobre como sair do localhost e quando usar o Tailscale, o Tailscale cria redes privadas permanentes sem depender de serviços intermediários.
Dados altamente sensíveis: Se os dados que trafegam pelo túnel são confidenciais, avalie um bore em VPS própria ou configure o Cloudflare Tunnel com atenção às políticas de privacidade do serviço.

Resumo

O ngrok é uma das ferramentas mais úteis no arsenal de qualquer desenvolvedor que trabalha com servidores locais. Ele resolve com um comando problemas que antes demandavam configuração de roteador, IP fixo ou deploy de ambiente de testes.

Para desenvolvimento do dia a dia, especialmente para testes de webhook e demonstrações rápidas, dificilmente você vai encontrar algo mais prático. Para necessidades mais permanentes ou com requisitos de privacidade mais rígidos, o Cloudflare Tunnel ou uma solução self-hosted com o bore são as alternativas mais adequadas.

Fontes e leituras complementares

Quer ir além do localhost?

No Flateek, cobrimos desenvolvimento, redes e self-host com linguagem acessível para todos os níveis. Assine nossa newsletter gratuita e receba nossos guias práticos diretamente no seu e-mail.