Murad Library
Info
Murad LibraryREF-0323MD

ngrok: o que é, como funciona, prós, contras e quando usar

Catalogued
Reading
15 min read

Autor/compilação: Pablo Murad - 2026
Tema: redes, túneis, localhost público, CGNAT, desenvolvimento web e hospedagem temporária

1. Introdução

O ngrok é uma ferramenta que permite expor um serviço local para a internet por meio de um túnel seguro. Em termos simples: você tem uma aplicação rodando no seu computador, servidor caseiro, Raspberry Pi ou máquina em uma rede com CGNAT, e o ngrok cria uma URL pública que encaminha acessos externos para esse serviço.

Exemplo clássico:

ngrok http 3000

Se você tem uma aplicação rodando em localhost:3000, esse comando pode gerar uma URL pública parecida com:

https://alguma-coisa.ngrok-free.app

Quem acessar essa URL chega ao seu serviço local, mesmo que ele esteja atrás de firewall, NAT ou CGNAT.

A ideia é poderosa, mas precisa ser entendida direito. O ngrok não transforma magicamente sua internet residencial em datacenter. Ele é uma ponte. Essa ponte pode ser extremamente útil para testes, desenvolvimento, webhooks, demonstrações e acesso remoto, mas nem sempre é a melhor escolha para produção séria.

2. O problema que o ngrok resolve

Normalmente, para hospedar um site ou API em casa, você precisaria de algumas coisas:

  1. um IP público acessível;
  2. portas abertas no roteador, como 80 e 443;
  3. DNS apontando para seu IP;
  4. configuração de firewall;
  5. HTTPS;
  6. algum servidor web, como Caddy, Nginx ou Apache.

O problema é que muita gente está atrás de CGNAT. Nesse cenário, o IP público não está diretamente no seu roteador. Ele é compartilhado pela operadora com vários clientes. Mesmo que você configure port forwarding no seu roteador, a conexão externa não chega até sua rede.

O ngrok contorna isso porque ele não exige conexão entrando diretamente na sua casa. O agente do ngrok instalado na sua máquina abre uma conexão de saída até a infraestrutura da ngrok. Depois, a URL pública fornecida pelo ngrok encaminha o tráfego por esse túnel até seu serviço local.

Ou seja, em vez de:

Internet -> seu IP público -> roteador -> servidor local

fica assim:

Internet -> ngrok cloud -> túnel seguro -> seu servidor local

Essa diferença é o motivo pelo qual o ngrok funciona tão bem em redes com CGNAT, firewall restritivo e ambientes onde você não controla o roteador.

3. Como o ngrok funciona por baixo

O funcionamento básico é:

  1. você instala o agente do ngrok na máquina local;
  2. autentica esse agente com sua conta;
  3. executa um comando apontando para uma porta local;
  4. o agente cria uma conexão TLS de saída com a nuvem da ngrok;
  5. a ngrok gera um endpoint público;
  6. requisições feitas ao endpoint público são encaminhadas pelo túnel até sua aplicação.

Exemplo:

ngrok http 8080

Se sua aplicação está em:

http://localhost:8080

O ngrok cria uma URL pública HTTPS e encaminha tudo para essa porta.

A documentação oficial descreve esse modelo como túneis seguros entre a nuvem da ngrok e a máquina local, usando conexão de saída pela porta 443, sem necessidade de abrir portas ou alterar firewall.

4. Principais usos do ngrok

4.1 Testar webhooks

Esse é um dos usos mais comuns.

Muitos serviços precisam enviar requisições para sua aplicação:

  • Stripe;
  • GitHub;
  • GitLab;
  • Telegram bots;
  • WhatsApp APIs;
  • Discord bots;
  • sistemas de pagamento;
  • automações;
  • plataformas de e-mail;
  • integrações com CRM.

O problema é que, durante o desenvolvimento, sua aplicação está em localhost, e serviços externos não conseguem chamar localhost da sua máquina.

Com ngrok:

ngrok http 5000

Você pega a URL pública e cadastra como webhook:

https://exemplo.ngrok-free.app/webhook

Agora o serviço externo consegue chamar sua aplicação local.

4.2 Mostrar um projeto para outra pessoa

Você está desenvolvendo uma landing page, sistema, painel ou protótipo. Em vez de subir tudo em uma VPS ou hospedagem, você roda localmente e compartilha a URL do ngrok.

Exemplo:

npm run dev
ngrok http 5173

Isso é útil para mostrar rapidamente um projeto feito com Vite, React, Vue, Svelte ou qualquer servidor local.

4.3 Acessar serviços locais remotamente

Você pode expor temporariamente uma interface local:

ngrok http 8080

Isso pode servir para acessar:

  • painel de administração;
  • dashboard interno;
  • aplicação Flask/FastAPI;
  • servidor Node.js;
  • app em Docker;
  • sistema rodando em Raspberry Pi;
  • ambiente de teste.

Mas aqui entra uma regra importante: não exponha painel sensível sem autenticação. Se você publicar um serviço mal protegido na internet, ele estará realmente na internet.

4.4 Hospedar algo temporariamente atrás de CGNAT

Se você tem internet residencial com CGNAT, o ngrok é uma saída rápida para publicar temporariamente um site ou API.

Exemplo com Caddy:

:8080 {
    root * /var/www/site
    file_server
}

Depois:

ngrok http 8080

Fluxo:

Visitante -> URL pública do ngrok -> seu Caddy local -> arquivos do site

Funciona. Só não confunda isso com hospedagem profissional de longo prazo.

4.5 Expor serviços TCP

Além de HTTP/HTTPS, o ngrok também suporta endpoints TCP e TLS. Isso pode ser usado para alguns serviços que não são web, como conexões TCP brutas.

Exemplo conceitual:

ngrok tcp 22

Isso poderia expor SSH por um endpoint TCP da ngrok. Porém, isso exige muito cuidado. Expor SSH publicamente, mesmo via túnel, não é brincadeira. Use chave SSH, restrições e autenticação forte.

5. Protocolos suportados

O ngrok trabalha principalmente com:

  • HTTP/HTTPS: ideal para sites, APIs, webhooks e aplicações web;
  • TCP: para serviços TCP genéricos;
  • TLS: para serviços que já usam TLS e precisam de roteamento baseado em SNI.

Para a maioria dos projetos web, você usará:

ngrok http PORTA

Exemplos:

ngrok http 80
ngrok http 3000
ngrok http 5000
ngrok http 8000
ngrok http 8080

6. ngrok e HTTPS

Uma vantagem prática do ngrok é que ele entrega uma URL pública HTTPS sem você precisar configurar certificado manualmente.

Você não precisa instalar Certbot, configurar Let's Encrypt, mexer em server_name, gerar certificado, renovar certificado ou abrir a porta 443 no seu roteador. O ngrok cuida da parte pública do HTTPS.

Para desenvolvimento e teste, isso é excelente.

Para produção, depende. Em muitos casos, você vai querer domínio próprio, política de segurança, logs, controle de autenticação, disponibilidade e custo previsível.

7. ngrok com domínio próprio

O ngrok permite usar domínios personalizados, mas isso depende do plano e das configurações disponíveis na conta.

A lógica é:

seudominio.com -> ngrok -> túnel -> seu servidor local

Com isso, você pode ter algo como:

https://app.seudominio.com

apontando para uma aplicação local.

Isso é útil, mas precisa ser avaliado com calma. Se o objetivo for hospedar um site público permanente, talvez uma VPS com Caddy/Nginx seja mais simples, barata e previsível.

8. ngrok com Caddy

ngrok e Caddy podem trabalhar juntos.

O Caddy pode servir ou rotear os serviços localmente, enquanto o ngrok expõe o Caddy para a internet.

Exemplo:

:8080 {
    root * /var/www/meusite
    file_server
}

Depois:

ngrok http 8080

Ou, com proxy reverso:

:8080 {
    reverse_proxy localhost:3000
}

Nesse caso:

Internet -> ngrok -> Caddy -> app Node/Python/etc.

Esse arranjo é especialmente útil quando você está em CGNAT.

9. ngrok com Docker

Você pode usar ngrok junto com Docker de duas formas.

9.1 Rodando ngrok no host

Sua aplicação roda em Docker, exposta em uma porta local:

services:
  app:
    image: minha-app
    ports:
      - "3000:3000"

Depois, no host:

ngrok http 3000

Essa é a forma mais simples.

9.2 Rodando ngrok como container

Também é possível rodar o agente do ngrok em container e apontar para outro serviço na mesma rede Docker.

Exemplo conceitual:

services:
  app:
    image: minha-app
    expose:
      - "3000"

  ngrok:
    image: ngrok/ngrok:latest
    command: http app:3000
    environment:
      - NGROK_AUTHTOKEN=SEU_TOKEN_AQUI

Essa abordagem é útil para ambientes reproduzíveis, mas exige cuidado com token, rede e persistência de configuração.

10. Instalação básica

O fluxo típico é:

  1. criar conta no ngrok;
  2. baixar o agente;
  3. adicionar o authtoken;
  4. iniciar um túnel.

Exemplo genérico:

ngrok config add-authtoken SEU_TOKEN
ngrok http 3000

Depois disso, o ngrok mostra a URL pública no terminal.

11. Arquivo de configuração

Para usos mais organizados, você pode configurar túneis em um arquivo YAML.

Exemplo conceitual:

version: "3"
agent:
  authtoken: SEU_TOKEN
endpoints:
  - name: app-local
    url: app.seudominio.com
    upstream:
      url: 3000

A sintaxe exata pode variar conforme a versão e o modelo de endpoint usado. Em ambiente real, consulte a documentação atual antes de copiar configuração antiga da internet. O ngrok mudou bastante ao longo dos anos, e muito tutorial velho está defasado.

12. Recursos de segurança

O ngrok não é só um túnel burro. Ele também oferece recursos de segurança e controle, dependendo do plano e da configuração:

  • autenticação;
  • OAuth;
  • políticas de tráfego;
  • inspeção de requisições;
  • replay de requisições;
  • domínios reservados;
  • controle de endpoints;
  • logs;
  • integração com APIs;
  • regras para manipular ou bloquear tráfego.

Para desenvolvimento, a inspeção de tráfego é muito útil. Você consegue ver requisições recebidas, headers, payloads e respostas. Para debugar webhooks, isso economiza tempo.

13. Vantagens do ngrok

13.1 Funciona atrás de CGNAT

Essa é a grande vantagem. Você não precisa de IP público direto.

13.2 Não exige abrir portas

O agente conecta para fora. Na maioria das redes, conexões de saída pela porta 443 são permitidas.

13.3 HTTPS fácil

Você ganha uma URL HTTPS rapidamente, sem mexer com certificados.

13.4 Excelente para webhooks

Para testar integração com serviços externos, o ngrok é uma das ferramentas mais práticas.

13.5 Rápido para demonstrações

Você mostra uma aplicação local para alguém sem publicar em servidor definitivo.

13.6 Multiplataforma

Roda em Linux, macOS, Windows e pode ser usado em servidores, notebooks, Raspberry Pi e containers.

13.7 Suporte a HTTP, TCP e TLS

Não fica limitado apenas a aplicações web simples.

14. Desvantagens do ngrok

14.1 Dependência de terceiro

Seu tráfego passa pela infraestrutura da ngrok. Se o serviço cair, sua exposição pública cai junto.

14.2 Custo e limites

Planos gratuitos costumam ter limitações. Recursos como domínios fixos, TCP avançado, limites maiores, times e recursos profissionais podem exigir plano pago. Não monte uma operação crítica em cima de plano gratuito achando que descobriu um hack infinito.

14.3 URL temporária no uso gratuito

Dependendo do plano/configuração, a URL pode mudar quando você reinicia o túnel. Isso é ruim para webhooks fixos, clientes, integrações e qualquer coisa que espere estabilidade.

14.4 Não substitui infraestrutura de produção

Para produção séria, você precisa pensar em disponibilidade, observabilidade, custo, segurança, backups, deploy, monitoramento e controle de domínio.

O ngrok pode participar de uma arquitetura profissional, mas usar ngrok http 3000 em um terminal aberto não é uma arquitetura profissional.

14.5 Risco de exposição acidental

Se você expõe um painel sem senha, uma API de administração ou um serviço de banco, ele pode ficar acessível para o mundo.

A ferramenta facilita publicar. Isso é vantagem e perigo ao mesmo tempo.

14.6 Latência e dependência geográfica

Como o tráfego passa por um intermediário, pode haver latência adicional em comparação com uma VPS bem posicionada.

14.7 Controle inferior ao de uma VPS própria

Em uma VPS com Caddy/Nginx, você controla sistema, rede, logs, firewall, certificados, processos e arquitetura. No ngrok, parte desse controle fica abstraído.

15. Quando usar ngrok

Use ngrok para:

  • testar webhooks;
  • mostrar protótipos;
  • expor localhost temporariamente;
  • acessar painel local por pouco tempo;
  • testar apps atrás de CGNAT;
  • desenvolver integrações;
  • validar MVPs;
  • conectar dispositivos remotos;
  • depurar chamadas HTTP externas.

16. Quando não usar ngrok

Evite ngrok como solução principal quando:

  • o site precisa ficar online 24/7;
  • o projeto é crítico;
  • você precisa de custo previsível em escala;
  • há tráfego alto;
  • há dados sensíveis sem camada forte de autenticação;
  • você precisa de controle total da infraestrutura;
  • o domínio e endpoint precisam ser permanentes e baratos;
  • você já tem VPS pública disponível.

Nesses casos, uma VPS com Caddy, Nginx ou Traefik provavelmente faz mais sentido.

17. ngrok vs Cloudflare Tunnel

Ambos resolvem um problema parecido: expor serviços locais sem abrir portas.

ngrok

Melhor para:

  • desenvolvimento;
  • webhooks;
  • testes rápidos;
  • inspeção/replay de requisições;
  • demos;
  • uso temporário.

Cloudflare Tunnel

Melhor para:

  • domínio próprio usando Cloudflare;
  • serviços mais permanentes;
  • acesso remoto com Zero Trust;
  • integração com ecossistema Cloudflare;
  • exposição contínua de serviços web.

Resumo direto: ngrok é excelente para desenvolvimento e túnel rápido; Cloudflare Tunnel costuma ser mais interessante para publicação contínua usando domínio próprio.

18. ngrok vs VPS

Uma VPS é um servidor público real. O ngrok é um túnel para uma máquina que pode estar escondida atrás de NAT.

Use ngrok quando:

  • você quer rapidez;
  • está testando;
  • está em CGNAT;
  • não quer configurar servidor;
  • precisa expor algo por algumas horas ou dias.

Use VPS quando:

  • quer produção;
  • quer estabilidade;
  • quer controle;
  • quer performance previsível;
  • quer hospedar vários serviços permanentemente;
  • quer arquitetura limpa.

A verdade simples: ngrok é ferramenta de ponte. VPS é infraestrutura.

19. Exemplo prático com app local

Suponha uma API FastAPI rodando em:

uvicorn main:app --host 127.0.0.1 --port 8000

Para expor:

ngrok http 8000

Agora você pode usar a URL gerada como endpoint público.

Se for webhook:

https://url-do-ngrok.ngrok-free.app/webhook

Se for teste de API:

curl https://url-do-ngrok.ngrok-free.app/status

20. Exemplo prático com Caddy e site estático

Crie uma pasta:

mkdir -p /var/www/lab
nano /var/www/lab/index.html

Conteúdo simples:

<h1>Meu site local via ngrok</h1>
<p>Servidor local, acesso público por túnel.</p>

Caddyfile:

:8080 {
    root * /var/www/lab
    file_server
}

Rode o Caddy:

caddy run --config Caddyfile

Em outro terminal:

ngrok http 8080

Pronto: seu site local está publicamente acessível pela URL do ngrok.

21. Cuidados de segurança

Algumas regras duras:

  1. Não exponha banco de dados diretamente.
  2. Não exponha painel admin sem autenticação.
  3. Não exponha SSH com senha fraca.
  4. Não compartilhe URL de túnel em lugar público sem necessidade.
  5. Não deixe túnel rodando esquecido.
  6. Não use ngrok como desculpa para ignorar firewall e autenticação.
  7. Não coloque token do ngrok em repositório público.

O ngrok facilita o acesso. Isso significa que ele também facilita erro operacional.

22. O erro mental mais comum

O erro é pensar:

“Agora posso hospedar tudo em casa sem pagar VPS.”

Tecnicamente, até dá para publicar muita coisa por túnel. Mas a pergunta real é:

“Isso é estável, seguro, barato, controlável e adequado para produção?”

Muitas vezes, a resposta é não.

Para laboratório e desenvolvimento, ótimo. Para produção séria, cuidado.

23. Arquiteturas recomendadas

23.1 Desenvolvimento local

App local -> ngrok -> internet

Simples e eficiente.

23.2 Servidor local com CGNAT

Internet -> ngrok -> Caddy local -> serviços internos

Bom para testes e serviços pequenos.

23.3 Produção simples

Internet -> VPS com Caddy -> aplicação

Mais previsível.

23.4 Produção híbrida

Internet -> VPS pública -> VPN/WireGuard/Tailscale -> servidor local

Mais profissional que depender apenas de túnel temporário.

24. Minha opinião direta

O ngrok é uma ferramenta excelente, mas não é uma varinha mágica.

Ele resolve muito bem o problema de expor serviços locais rapidamente, especialmente quando você está atrás de CGNAT. Para webhooks, desenvolvimento e demonstrações, é uma das melhores ferramentas da categoria.

Mas usar ngrok como hospedagem permanente sem entender limites, custo e segurança é gambiarra. Pode funcionar, mas não confunda “funciona” com “é uma boa arquitetura”.

A recomendação prática é:

  • para testar: ngrok;
  • para CGNAT com publicação contínua: Cloudflare Tunnel ou VPS intermediária;
  • para produção real: VPS com Caddy/Nginx ou arquitetura híbrida bem desenhada;
  • para webhook local: ngrok sem medo, porque ele brilha nisso.

25. Conclusão

O ngrok é uma ponte entre o mundo externo e sua máquina local. Ele cria túneis seguros, permite URLs públicas, ajuda a testar webhooks, facilita demonstrações e contorna CGNAT sem precisar abrir portas no roteador.

Seu valor está na velocidade. Em poucos segundos, uma aplicação local pode ser acessada pela internet.

Seu risco também está na velocidade. Em poucos segundos, você pode expor algo que não deveria estar público.

Use ngrok como ferramenta de desenvolvimento, teste e acesso temporário. Para produção, pense duas vezes. Para infraestrutura crítica, pense três.

Fontes e leitura recomendada

Did this resonate?

Related documents