Execução local, túnel HTTPS e disponibilidade para o ChatGPT

1. localhost — é só para você, não para o ChatGPT

Vamos começar pelo principal “curto-circuito” cognitivo deste módulo. Você abre http://localhost:3000 no navegador, tudo funciona perfeitamente, o Next.js sorri, o widget renderiza. Parece lógico: “Já que tenho uma URL, vamos simplesmente entregá-la ao ChatGPT”.

O problema é que localhost não é “um domínio mágico da minha máquina na internet”. É um nome especial que sempre aponta para a mesma máquina onde o navegador ou cliente está rodando. Seu notebook fala consigo mesmo. Os servidores da OpenAI, onde o ChatGPT roda, também sabem falar com localhost… mas com o deles — dentro do datacenter. Enquanto isso, seu Next.js está confortavelmente escondido atrás do roteador doméstico, NAT e, possivelmente, de uma VPN corporativa.

Nesta aula nós:

• vamos entender por que localhost não está acessível para o ChatGPT;
• vamos configurar um túnel HTTPS via cloudflared de localhost:3000 até uma URL pública;
• vamos conectar essa URL no ChatGPT Dev Mode;
• vamos verificar a cadeia “código → túnel → ChatGPT” com uma mudança simples no widget e discutir armadilhas comuns.

Disso derivam dois fatos simples:

1. O ChatGPT não sabe onde seu notebook está.
2. Mesmo que soubesse, não conseguiria acessá-lo diretamente — conexões de entrada estão fechadas.

Além disso, o ChatGPT funciona apenas com endpoints HTTPS públicos (pontos de entrada): é preciso um domínio “normal” e um certificado TLS. Por segurança, os servidores da OpenAI não acessam endereços HTTP arbitrários sem criptografia, portanto é necessário um domínio HTTPS com certificado válido. Apenas expor http://meu‑IP‑externo:3000 — já não é opção.

Precisamos, portanto, de um intermediário — um serviço que:

1. Viva na internet com um domínio HTTPS “normal”.
2. Consiga encaminhar com segurança as requisições desse domínio para seu localhost:3000.

Isto é o que chamamos de túnel HTTPS.

2. O que é um túnel HTTPS: modelo intuitivo

Deixando os termos assustadores de lado, um túnel é um serviço que lhe fornece uma URL pública temporária (ou permanente) e repassa todas as requisições dessa URL para sua porta local. Em termos de rede, é basicamente um servidor de proxy reverso (reverse proxy) que mantém uma conexão de saída com a nuvem.

Analogia intuitiva: você está sentado atrás de uma porta fechada (o roteador de casa), e o túnel é um mensageiro que fica do lado de fora com uma placa “toda correspondência aqui”, às vezes entra por uma porta de serviço e entrega as cartas diretamente nas suas mãos.

O caminho da requisição fica mais ou menos assim:

sequenceDiagram
    participant ChatGPT as ChatGPT (nuvem)
    participant Tunnel as Túnel HTTPS
(Cloudflare / ngrok)
    participant Dev as Seu servidor de desenvolvimento
(localhost:3000)

    ChatGPT->>Tunnel: Requisição HTTPS para https://xyz.trycloudflare.com
    Tunnel->>Dev: Requisição HTTP para http://localhost:3000
    Dev-->>Tunnel: Resposta do Next.js
    Tunnel-->>ChatGPT: Resposta HTTPS

Pontos-chave aqui.

Primeiro, o iniciador da conexão com o serviço de túnel é você. A ferramenta (cloudflared, ngrok etc.) estabelece por conta própria a conexão de saída com a nuvem. Isso quase sempre é permitido mesmo atrás de NAT/firewall.

Segundo, o serviço de túnel fornece um domínio HTTPS com certificado válido, então não é preciso levantar TLS autoassinado manualmente.

Terceiro, para o ChatGPT seu App parece um serviço web comum com domínio HTTPS. Ele não suspeita que, dali em diante, o tráfego vá para o notebook de alguém.

3. Quais túneis existem e o que vamos usar no curso

No ecossistema de desenvolvimento web há algumas soluções populares para essa tarefa:

• ngrok — clássico do gênero, por muito tempo foi o padrão de fato de “como expor o local para fora”.
• Cloudflare Tunnel (cloudflared) — solução moderna e gratuita da Cloudflare, dá um domínio do tipo *.trycloudflare.com mesmo sem cadastro; você também pode anexar seu próprio domínio se quiser.
• LocalTunnel — mínimo de magia, apenas um pacote npm que fornece uma URL HTTPS temporária como https://something.loca.lt.

Todos resolvem a mesma tarefa: dar a um servidor local um domínio HTTPS público, adequado para o ChatGPT.

Para o curso, não queremos dispersar a atenção, então como “ferramenta principal” usaremos o Cloudflare Tunnel com a utilidade cloudflared. As razões são simples: não exige cadastro para túneis rápidos, fornece HTTPS de verdade e é fácil de iniciar com um único comando.

Ainda assim, se você já é fã do ngrok — sem problema. Os comandos serão um pouco diferentes, mas o conceito é o mesmo: ngrok http 3000 em vez de cloudflared tunnel --url http://localhost:3000.

Para facilitar a orientação, vamos resumir as ferramentas em uma tabela curta.

https://*.trycloudflare.com

https://*.ngrok.app

https://*.loca.lt

Nesta aula vamos nos concentrar no Cloudflare Tunnel no modo “túnel rápido e descartável”. Isso é mais do que suficiente para “fazer amizade” entre seu Next.js e o ChatGPT no Dev Mode.

4. Verificando se o Next.js local está rodando

Antes de expor qualquer coisa por um túnel, é preciso garantir que o servidor local está realmente funcionando. Caso contrário, você vai depurar o túnel quando, na verdade, o problema é que o Next.js simplesmente não está rodando.

Relembrando a ordem padrão:

# a partir da raiz do projeto com o template do Apps SDK
npm install      # se ainda não fez
npm run dev      # iniciar o servidor de desenvolvimento do Next.js

Por padrão, o Next.js 16 sobe em http://localhost:3000 (se a porta não estiver ocupada). No terminal você verá algo como:

ready - started server on 0.0.0.0:3000, url: http://localhost:3000

Abra no navegador http://localhost:3000 e confirme que a página do template abre. Este é o seu “laboratório local”. Se algo não funcionar aqui (erro de build, o TypeScript reclama, porta ocupada) — conserte isso primeiro e só depois passe para o túnel.

5. Iniciando o Cloudflare Tunnel: de localhost ao HTTPS público

Vamos à parte mais saborosa — fazer com que qualquer pessoa na internet (incluindo o ChatGPT) possa abrir seu Next.js por uma URL HTTPS.

Instalação do cloudflared

O método de instalação depende do SO. No macOS, o caminho mais simples é via Homebrew:

brew install cloudflare/cloudflare/cloudflared

No Windows e no Linux, você pode baixar o binário pronto ou usar um gerenciador de pacotes, conforme recomenda a documentação da Cloudflare (os links estão nos materiais complementares do módulo).

Verifique a instalação com:

cloudflared --version

Se a ferramenta não for encontrada, verifique o PATH ou reinicie o terminal.

Túnel rápido e descartável

Nosso objetivo agora é um túnel mínimo funcional, sem conta, domínio ou configs complexas. Para isso o cloudflared tem o modo quick tunnel, que fornece uma URL no domínio trycloudflare.com.

Com o npm run dev em execução, rode em outro terminal:

cloudflared tunnel --url http://localhost:3000

Guarde a regra simples: HTTPS — por fora, HTTP — por dentro. O cloudflared fornece para você um domínio HTTPS do lado de fora, mas acessa seu localhost:3000 via HTTP comum.

Após um log curto, você verá uma linha como:

INF +-------------------------------------------------------------+
INF |  Your quick Tunnel has been created!                        |
INF |  https://giftgenius-1234.trycloudflare.com                  |
INF +-------------------------------------------------------------+

Esse https://giftgenius-1234.trycloudflare.com é o novo endereço público do seu aplicativo local. O túnel recebe requisições HTTPS nesse domínio e as encaminha para http://localhost:3000.

Alguns pontos importantes.

Primeiro, o terminal com o cloudflared deve permanecer aberto enquanto você precisar do túnel. Assim que você fechá-lo (ou pressionar Ctrl+C), o túnel cai e a URL para de funcionar.

Segundo, a cada execução do quick tunnel a URL pode ser nova. Para nosso desenvolvimento didático isso é normal: o objetivo deste módulo é apenas dar ao ChatGPT acesso ao seu Next.js local por qualquer endereço HTTPS funcional. Mas isso significa que às vezes será preciso atualizar a URL no ChatGPT Dev Mode. No módulo 7 vamos voltar ao tema de túneis e configurar um domínio de desenvolvimento estável, para não ficar correndo atrás de endereços.

Testando o túnel como um site comum

Antes de conectar tudo ao ChatGPT, verifique se o túnel está simplesmente acessível da internet.

1. Abra a https://...trycloudflare.com obtida no navegador.
2. Você deve ver a mesma interface que em http://localhost:3000.
3. No console onde roda npm run dev, você verá novas requisições — isto é, o Next.js realmente está atendendo o acesso externo.

Se a página não abrir ou mostrar erro, verifique antes de tudo:

• Se o npm run dev está rodando.
• Se você não errou na URL local ao iniciar o túnel (http://localhost:3000, e não https:// nem a porta 3001).
• Se algo não está bloqueando conexões de saída (raro, mas pode acontecer em redes corporativas rígidas).

6. Encaminhando essa URL para o ChatGPT Dev Mode

Agora temos tudo para conectar a cadeia:

ChatGPT (nuvem) → seu túnel HTTPS → Next.js local.

A parte da interface do Dev Mode você já viu na aula anterior; agora vamos repetir o mesmo, mas com uma URL HTTPS real, e não algo teórico.

A sequência geral de ações no ChatGPT é esta.

Primeiro, abra o ChatGPT no navegador e vá para a seção de desenvolvedores (geralmente algo como “Developer”, “Apps”, “My apps” — os nomes podem mudar conforme o UI).

Crie um novo aplicativo ou edite o app de desenvolvimento existente, caso você já o tenha criado.

No campo onde é necessário informar a URL do seu App, indique o endereço raiz do túnel, por exemplo:

https://giftgenius-1234.trycloudflare.com/mcp

O ponto de entrada é o nosso /route/mcp.ts. Ao conectar, o ChatGPT começa por ele e, a partir daí, obtém todas as informações necessárias. No README do template pode estar indicado outro caminho, caso haja vários aplicativos; mas, por enquanto, considere que a URL raiz do túnel + /mcp é o que você precisa.

Salve a configuração do aplicativo. Nesse momento o ChatGPT faz várias requisições ao seu app através do túnel:

• Lê o manifesto do App (metadados, ferramentas etc.).
• Verifica a disponibilidade do endpoint MCP.
• Obtém a lista de todas as tools e recursos.
• Faz cache do código HTML de todos os widgets(!)

Se tudo estiver certo, você verá seu aplicativo na lista de Dev Apps. Se algo quebrar (manifesto inválido, servidor sem resposta, túnel caiu), o ChatGPT mostrará um erro como “App unavailable” ou algo parecido.

Importante: essa mesma URL HTTPS do túnel o ChatGPT usará tanto para chamadas de ferramentas (MCP) quanto para carregar o widget e os assets estáticos. Na próxima seção, vamos separar esses dois papéis.

7. Como as requisições trafegam agora: dois papéis do seu túnel

É importante entender com clareza o que exatamente o ChatGPT faz com essa URL. Na arquitetura do Apps SDK existem dois pontos de entrada principais: o endpoint MCP e o widget de UI.

De forma simplificada, a cadeia fica assim:

flowchart LR
    ChatGPT["ChatGPT (modelo)"] 
    subgraph Internet
        Tunnel[Túnel HTTPS
giftgenius-1234.trycloudflare.com]
    end
    Local["Servidor de desenvolvimento do Next.js http://localhost:3000"]

    ChatGPT -- Requisições HTTP(S) para /mcp --> Tunnel
    ChatGPT -- Carregamento do iframe /widget --> Tunnel
    Tunnel --> Local

O túnel tem, de fato, dois papéis principais:

• Papel 1: endpoint MCP (ferramentas). Quando o modelo decide chamar uma ferramenta (tool), ele faz um HTTP POST para o endpoint MCP (no template, isso é a rota app/mcp/route.ts no Next.js) no mesmo domínio do túnel.
• Papel 2: widget de UI e assets estáticos. Quando o modelo decide exibir um widget, ele incorpora um iframe com a sua URL (geralmente /widget ou o que for indicado no manifesto), e o carregamento também ocorre através do túnel.

Nesse sentido, o túnel não é “para uma coisa só”, ele é uma porta única para o seu App local: UI, MCP, estáticos — tudo passa pelo mesmo domínio HTTPS público.

8. Na prática: verificando a cadeia “código → túnel → ChatGPT”

Para se certificar de que tudo realmente funciona, e não apenas nas figuras, faça um cenário prático mínimo.

Primeiro, rode npm run dev e confirme que http://localhost:3000 abre no navegador.

Depois, rode cloudflared tunnel --url http://localhost:3000 e obtenha uma URL HTTPS pública. Teste-a em outro navegador ou até em outro dispositivo (por exemplo, no celular via rede móvel) — assim você garante que as requisições passam pela internet, e não ficam apenas na sua máquina.

Em seguida, abra o ChatGPT, vá para o Dev Mode e confirme que seu App está conectado a essa URL. No Composer, na conversa do ChatGPT, selecione seu App, inicie um diálogo e veja se o ChatGPT insere o widget e carrega sua UI.

Para ver claramente que é o seu código, altere algo bem simples no widget, por exemplo o título:

// app/widget/page.tsx (exemplo)
'use client';

export default function GiftGeniusWidget() {
  return <h1>GiftGenius através do túnel 🚇</h1>;
}

Depois de salvar o arquivo:

1. Aguarde o fast refresh do Next.js,
2. Vá à seção do ChatGPT onde você adicionou seu aplicativo e atualize (refresh) o app,
3. Abra/atualize a sessão com o App no ChatGPT,
4. Faça uma nova solicitação ao ChatGPT pedindo para exibir seu widget,
5. Confirme que o novo texto do título está visível dentro do ChatGPT.

Este é o pequeno momento da verdade: você acabou de mudar o código na sua máquina, e a mudança apareceu na interface em nuvem do ChatGPT através do túnel.

9. Um pouco sobre segurança e “o que exatamente você expôs”

Qualquer túnel não é um brinquedo, mas sim uma entrada pública real para a sua máquina. No nosso cenário didático estamos expondo apenas o localhost:3000, onde roda o aplicativo Next.js. Isso é relativamente seguro se:

• essa porta não for usada para mais nada;
• você não tiver um “aplicativo monstro” que inclua, por algum motivo, um painel admin do banco de dados, phpMyAdmin e mais quatro serviços de demo.

Algumas regras práticas importantes.

O túnel é uma ferramenta de desenvolvimento, não um ambiente de produção. Estamos usando conscientemente no Dev Mode, não para usuários de verdade e muito menos para processar pagamentos.

Evite executar nessa mesma porta (3000) quaisquer painéis administrativos, bancos sem senha e coisas do tipo. Tudo o que responder nessa porta ficará visível da internet enquanto o túnel estiver ativo.

Não compartilhe sua URL trycloudflare.com por aí. Sim, a probabilidade de alguém começar a escaneá-la ativamente enquanto você faz um projeto didático é baixa. Mas o hábito de “jogar o link do servidor de dev em qualquer lugar” pode cobrar seu preço na produção.

Mais adiante, quando chegarmos aos tópicos sobre Vercel e ambiente de produção, usaremos hospedagem “de verdade”, com domínios estáveis e segurança de produção, e o túnel continuará sendo uma ferramenta apenas para desenvolvimento.

10. Erros comuns ao trabalhar com execução local e túnel

Então, já temos o Next.js local rodando, um túnel HTTPS funcional e o Dev Mode conectado no ChatGPT. Para encerrar — alguns erros comuns que quase todo mundo comete nas primeiras tentativas e como diagnosticá-los rapidamente.

Erro nº 1: tentar usar http://localhost:3000 diretamente no ChatGPT.
Às vezes iniciantes simplesmente colam essa URL na config do Dev Mode e se surpreendem quando o ChatGPT diz que não consegue acessar o App. Relembrando: localhost é “eu mesmo” para quem faz a requisição. Para o ChatGPT isso é o servidor da OpenAI, não o seu notebook. Você não verá logs em sua máquina porque as requisições nem chegam até ela.

Erro nº 2: iniciar o túnel para uma porta inexistente ou incorreta.
Cenário comum: um dia você rodou npm run dev na porta 3000, o servidor já caiu, mas no segundo terminal, por hábito, você inicia cloudflared tunnel --url http://localhost:3000. A Cloudflare fornece um belo domínio HTTPS, mas, ao abrir, aparece erro. O diagnóstico é simples: o servidor local não está vivo. Sempre verifique primeiro http://localhost:3000 no navegador e só então ligue o túnel.

Erro nº 3: confusão entre http:// e https:// ao iniciar o túnel.
O túnel fornece HTTPS do lado de fora, mas precisa acessar o servidor local por HTTP, por exemplo http://localhost:3000. Tentar indicar https://localhost:3000 costuma levar a erros estranhos de TLS por dentro ou simplesmente à indisponibilidade. Lembre-se da regra: HTTPS — por fora, HTTP — por dentro.

Erro nº 4: fechar o terminal com o túnel enquanto testa ativamente no ChatGPT.
Outro caso clássico: tudo configurado, o App funciona no ChatGPT, e então você fecha por engano a janela do terminal com o cloudflared. Dez minutos depois, você volta ao ChatGPT — e vê “App unavailable”. A razão é simples: a URL ficou nas configurações do App, mas o túnel foi desligado. Regra de ouro: enquanto você testa o App no Dev Mode, o terminal com o túnel deve continuar rodando.

Erro nº 5: usar sem perceber uma nova URL após reiniciar o túnel.
No modo quick tunnel, a Cloudflare fornece um novo *.trycloudflare.com a cada execução. Se você parou e iniciou novamente o cloudflared, mas no ChatGPT permanece a URL antiga, o ChatGPT continuará acessando aquele endereço e obtendo timeouts ou outro serviço. Ao mudar a URL do túnel, sempre atualize-a nas configurações do Dev Mode. Mais tarde vamos falar sobre como ter um domínio de desenvolvimento estável para não ficar correndo atrás de URLs.

Erro nº 6: expor serviços extras ou perigosos na mesma porta.
Às vezes, por comodidade, desenvolvedores rodam na porta 3000 não só o Next.js, mas também várias “utilidades”: painel de depuração, API experimental sem autenticação e por aí vai. Assim que você expõe essa porta via túnel, todas essas coisas ficam acessíveis de fora. Em um projeto didático, talvez nada grave aconteça, mas esse hábito em projetos reais aumenta muito o risco de vazamentos e invasões. Tenha sempre em mente: tudo que responde na porta indicada no túnel fica visível na internet.