Lokalne uruchomienie, tunel HTTPS i dostępność dla ChatGPT

1. localhost — jest tylko dla ciebie, a nie dla ChatGPT

Zacznijmy od głównego dysonansu poznawczego tego modułu. Otwierasz http://localhost:3000 w przeglądarce, wszystko pięknie działa, Next.js się uśmiecha, widżet się renderuje. Wydaje się logiczne: „Skoro mam URL, po prostu podam go ChatGPT”.

Problem w tym, że localhost to nie „magiczna domena mojego komputera w internecie”. To specjalna nazwa, która zawsze wskazuje na tę samą maszynę, na której uruchomiono przeglądarkę lub klienta. Twój laptop zwraca się do samego siebie. Serwery OpenAI, na których działa ChatGPT, też potrafią zwracać się do localhost… ale do swojego — wewnątrz centrum danych. A twój Next.js jest szczęśliwie schowany za domowym routerem, NAT‑em i, być może, firmowym VPN‑em.

W tej lekcji:

• zrozumiemy, dlaczego localhost jest niedostępny dla ChatGPT;
• skonfigurujemy tunel HTTPS przez cloudflared z localhost:3000 do publicznego URL;
• podłączymy ten URL w ChatGPT Dev Mode;
• sprawdzimy łańcuch „kod → tunel → ChatGPT” na prostej zmianie w widżecie i omówimy typowe pułapki.

Z tego wynikają dwa proste fakty:

1. ChatGPT nie wie, gdzie znajduje się twój laptop.
2. Nawet gdyby wiedział, i tak nie może połączyć się z nim bezpośrednio — połączenia przychodzące są zablokowane.

Co więcej, ChatGPT zasadniczo działa tylko z publicznymi punktami końcowymi HTTPS (punktami wejścia): potrzebna jest normalna domena i certyfikat TLS. Serwery OpenAI ze względów bezpieczeństwa nie łączą się z dowolnymi adresami HTTP bez szyfrowania, dlatego potrzebna jest właśnie domena HTTPS z ważnym certyfikatem. Samo wystawienie na zewnątrz http://mój‑zewnętrzny‑IP:3000 — już nie wchodzi w grę.

Dlatego potrzebny jest pośrednik — serwis, który:

1. Żyje w internecie z normalną domeną HTTPS.
2. Potrafi bezpiecznie przekazywać żądania z tej domeny do twojego localhost:3000.

To właśnie tunel HTTPS.

2. Czym jest tunel HTTPS: intuicyjny model

Jeśli odrzucić wszystkie straszne słowa, tunel to usługa, która daje ci tymczasowy (lub stały) publiczny URL i przesyła wszystkie żądania stamtąd na twój lokalny port. W terminologii sieciowej to w istocie serwer reverse proxy, który utrzymuje połączenie wychodzące z chmurą.

Intuicyjna analogia: siedzisz za zamkniętymi drzwiami (domowy router), a tunel to kurier, który stoi na zewnątrz z tabliczką „wszystkie listy tutaj”, czasem wpada do ciebie tylnymi drzwiami i wręcza listy do rąk.

Schemat drogi żądania wygląda mniej więcej tak:

sequenceDiagram
    participant ChatGPT as ChatGPT (chmura)
    participant Tunnel as Tunel HTTPS
(Cloudflare / ngrok)
    participant Dev as Twój serwer deweloperski
(localhost:3000)

    ChatGPT->>Tunnel: Żądanie HTTPS do https://xyz.trycloudflare.com
    Tunnel->>Dev: Żądanie HTTP do http://localhost:3000
    Dev-->>Tunnel: Odpowiedź Next.js
    Tunnel-->>ChatGPT: Odpowiedź HTTPS

Kluczowe momenty są następujące.

Po pierwsze, inicjatorem połączenia z usługą tunelową jesteś ty. Narzędzie (cloudflared, ngrok itd.) samo nawiązuje połączenie wychodzące z chmurą. To prawie zawsze jest dozwolone nawet za NAT‑em/firewallem.

Po drugie, usługa tunelowa przydziela ci domenę HTTPS z ważnym certyfikatem, więc nie trzeba ręcznie stawiać samopodpisanego TLS.

Po trzecie, dla ChatGPT twój App wygląda jak zwykły serwis WWW z domeną HTTPS. Nie domyśla się, że dalej ruch trafia na czyjegoś laptopa.

3. Jakie są tunele i co wybierzemy w kursie

W ekosystemie web‑developmentu istnieje kilka popularnych rozwiązań do takiego zadania:

• ngrok — klasyka gatunku, przez długi czas był de facto standardem „jak pokazać lokalny serwer na zewnątrz”.
• Cloudflare Tunnel (cloudflared) — nowoczesne darmowe rozwiązanie od Cloudflare, daje domenę w formacie *.trycloudflare.com nawet bez rejestracji; w razie potrzeby możesz podpiąć własną domenę.
• LocalTunnel — minimum magii, po prostu pakiet npm, który wydaje tymczasowy adres HTTPS w rodzaju https://something.loca.lt.

Wszystkie one rozwiązują to samo zadanie: dać lokalnemu serwerowi publiczną domenę HTTPS, która pasuje do ChatGPT.

W kursie zależy nam na skupieniu uwagi, dlatego jako „główne” narzędzie weźmiemy Cloudflare Tunnel z narzędziem cloudflared. Powody są proste: nie wymaga rejestracji do szybkich tuneli, zapewnia normalny HTTPS, łatwo startuje jednym poleceniem.

Jeśli jednak jesteś fanem ngrok — nic złego. Polecenia będą trochę inne, ale koncepcja jeden do jednego: ngrok http 3000 zamiast cloudflared tunnel --url http://localhost:3000.

Aby łatwiej się zorientować, zbierzmy narzędzia w małej tabeli.

https://*.trycloudflare.com

https://*.ngrok.app

https://*.loca.lt

W tej lekcji skupimy się na Cloudflare Tunnel w trybie „szybki jednorazowy tunel”. To w zupełności wystarczy, aby „zaprzyjaźnić” twój Next.js z ChatGPT w Dev Mode.

4. Sprawdzamy, że lokalny Next.js działa

Zanim wystawisz coś na zewnątrz przez tunel, upewnij się, że lokalny serwer faktycznie działa. W przeciwnym razie będziesz debugować tunel, choć problemem jest to, że Next.js po prostu nie został uruchomiony.

Przypomnę standardową kolejność:

# z katalogu głównego projektu z szablonem Apps SDK
npm install      # jeśli jeszcze nie robiono
npm run dev      # uruchomienie dev-serwera Next.js

Domyślnie Next.js 16 uruchomi się na http://localhost:3000 (jeśli port nie jest zajęty). W terminalu zobaczysz coś w stylu:

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

Otwórz w przeglądarce http://localhost:3000 i upewnij się, że strona szablonu się otwiera. To twoje „lokalne laboratorium”. Jeśli tutaj coś nie działa (błąd kompilacji, TypeScript zgłasza błędy, port zajęty) — najpierw to napraw, potem przechodź do tunelu.

5. Uruchamiamy Cloudflare Tunnel: od localhost do publicznego HTTPS

Przechodzimy do sedna — sprawimy, aby każdy w internecie (w tym ChatGPT) mógł otworzyć twój Next.js pod adresem HTTPS‑URL.

Instalacja cloudflared

Sposób instalacji zależy od systemu operacyjnego. Najprostsza droga dla macOS — przez Homebrew:

brew install cloudflare/cloudflare/cloudflared

Na Windows i Linux możesz pobrać gotowy plik binarny lub użyć menedżera pakietów, zgodnie z zaleceniami dokumentacji Cloudflare (linki znajdziesz w materiałach dodatkowych modułu).

Sprawdzić instalację możesz poleceniem:

cloudflared --version

Jeśli narzędzie nie zostało znalezione, sprawdź PATH lub zrestartuj terminal.

Szybki jednorazowy tunel

Naszym celem teraz jest minimalny działający tunel, bez konta, domeny i skomplikowanych konfiguracji. Do tego cloudflared ma tryb quick tunnel, który daje URL w domenie trycloudflare.com.

Przy uruchomionym npm run dev wykonaj w innym terminalu:

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

Zapamiętaj prostą zasadę: HTTPS — na zewnątrz, HTTP — do środka. cloudflared sam przydziela ci na zewnątrz domenę HTTPS, ale do twojego localhost:3000 łączy się zwykłym HTTP.

Po krótkim logu zobaczysz wiersz w rodzaju:

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

Ten https://giftgenius-1234.trycloudflare.com — to nowy publiczny adres twojej lokalnej aplikacji. Tunel przyjmuje żądania HTTPS na tę domenę i przekazuje je do http://localhost:3000.

Kilka ważnych kwestii.

Po pierwsze, terminal z cloudflared musi pozostać otwarty, dopóki tunel jest potrzebny. Gdy tylko go zamkniesz (lub naciśniesz Ctrl+C), tunel przestaje działać, a URL przestaje odpowiadać.

Po drugie, przy każdym uruchomieniu quick tunnel URL może być nowy. Do naszych celów edukacyjnych to w porządku: celem tego modułu jest po prostu dać ChatGPT dostęp do twojego lokalnego Next.js przez dowolny działający adres HTTPS. Oznacza to jednak, że w ChatGPT Dev Mode czasem trzeba będzie zaktualizować URL. W module 7 wrócimy do tematu tuneli i skonfigurujemy już pełnoprawną stabilną domenę deweloperską, aby nie gonić za adresami.

Sprawdzamy tunel jak zwykłą stronę

Zanim to wszystko podłączysz do ChatGPT, sprawdź, czy tunel jest po prostu dostępny z internetu.

1. Otwórz otrzymany https://...trycloudflare.com w przeglądarce.
2. Powinieneś zobaczyć ten sam interfejs, co na http://localhost:3000.
3. W konsoli, gdzie działa npm run dev, zobaczysz nowe żądania — czyli Next.js faktycznie obsługuje zewnętrzne połączenia.

Jeśli strona się nie otwiera lub pojawia się błąd, najpierw sprawdź:

• Czy działa npm run dev.
• Czy nie pomyliłeś lokalnego URL przy starcie tunelu (http://localhost:3000, a nie https:// i nie port 3001).
• Czy nic nie blokuje połączeń wychodzących (rzadko, ale zdarza się w restrykcyjnych sieciach korporacyjnych).

6. Przekazujemy ten URL do ChatGPT Dev Mode

Teraz mamy wszystko, aby spiąć łańcuch:

ChatGPT (chmura) → twój tunel HTTPS → lokalny Next.js.

Część dotyczącą interfejsu Dev Mode widziałeś w poprzednim wykładzie; teraz po prostu powtórzymy to samo, ale z prawdziwym adresem HTTPS, a nie teoretycznym.

Ogólna sekwencja działań w ChatGPT wygląda tak.

Najpierw otwórz ChatGPT w przeglądarce i przejdź do sekcji dla deweloperów (zwykle coś w rodzaju „Developer”, „Apps”, „My apps” — konkretne nazwy mogą zmieniać się wraz z aktualizacją UI).

Utwórz nową aplikację lub edytuj już istniejącą aplikację deweloperską, jeśli już ją masz.

W polu, w które należy wkleić URL twojego App, podaj adres główny tunelu, na przykład:

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

Punktem wejścia jest nasz /route/mcp.ts. ChatGPT przy podłączaniu zacznie od niego, a potem pobierze wszystkie potrzebne informacje. W README szablonu może być wskazane, jeśli potrzebna jest inna ścieżka (gdy aplikacji jest kilka); na razie przyjmujemy, że główny URL tunelu + /mcp — to to, czego potrzebujesz.

Zapisz konfigurację aplikacji. W tym momencie ChatGPT wykona kilka żądań do twojej aplikacji przez tunel:

• Odczyta manifest App (metadane, narzędzia itd.).
• Sprawdzi dostępność endpointu MCP.
• Pobierze listę wszystkich tools i zasobów.
• Keszuje kod HTML wszystkich widżetów(!)

Jeśli wszystko w porządku, zobaczysz swoją aplikację na liście Dev‑Apps. Jeśli coś jest zepsute (nieważny manifest, serwer nie odpowiada, tunel padł), ChatGPT pokaże błąd w rodzaju „App unavailable” lub coś podobnego.

Ważne: ten sam URL HTTPS tunelu ChatGPT będzie używać zarówno do wywoływania narzędzi (MCP), jak i do ładowania widżetu i zasobów statycznych. W następnym rozdziale omówimy te dwie role osobno.

7. Jak teraz płyną żądania: dwie role twojego tunelu

Ważne jest jasno rozumieć, co dokładnie ChatGPT robi z tym URL. W architekturze Apps SDK są dwa główne punkty wejścia: endpoint MCP i widżet UI.

Uproszczony łańcuch wygląda tak:

flowchart LR
    ChatGPT["ChatGPT (model)"] 
    subgraph Internet
        Tunnel[Tunel HTTPS
giftgenius-1234.trycloudflare.com]
    end
    Local["Serwer deweloperski Next.js http://localhost:3000"]

    ChatGPT -- Żądania HTTP(S) do /mcp --> Tunnel
    ChatGPT -- Ładowanie iframe /widget --> Tunnel
    Tunnel --> Local

Tunel ma w praktyce dwie główne role:

• Rola 1: endpoint MCP (narzędzia). Gdy model decyduje się wywołać narzędzie (tool), wykonuje HTTP POST na endpoint MCP (w szablonie jest to trasa app/mcp/route.ts w Next.js) pod tą samą domeną tunelu.
• Rola 2: widżet UI i zasoby statyczne. Gdy model postanawia pokazać widżet, osadza iframe z twoim URL (zwykle /widget lub to, co wskazano w manifeście), a ładowanie także idzie przez tunel.

Tunel nie jest „do jednej rzeczy”, to jedne drzwi do twojego lokalnego App: UI, MCP, statyki — wszystko przechodzi przez tę samą publiczną domenę HTTPS.

8. Praktyka: sprawdzamy łańcuch „kod → tunel → ChatGPT”

Aby upewnić się, że wszystko naprawdę działa, a nie tylko ładnie wygląda na schematach, wykonaj minimalny scenariusz praktyczny.

Po pierwsze, uruchom npm run dev i upewnij się, że http://localhost:3000 otwiera się w przeglądarce.

Po drugie, uruchom cloudflared tunnel --url http://localhost:3000 i uzyskaj publiczny adres HTTPS. Sprawdź go w innej przeglądarce lub nawet na innym urządzeniu (np. na telefonie przez internet mobilny) — dzięki temu masz pewność, że żądania idą przez internet, a nie kręcą się tylko na twojej maszynie.

Po trzecie, otwórz ChatGPT, przejdź do Dev Mode i upewnij się, że twoje App jest podłączone do tego URL. W Composerze w czacie ChatGPT wybierz swoje App, zacznij dialog i sprawdź, czy ChatGPT wstawia widżet i ładuje twój UI.

Aby wyraźnie zobaczyć, że to właśnie twój kod, możesz zmienić coś bardzo prostego w widżecie, np. nagłówek:

// app/widget/page.tsx (przykład)
'use client';

export default function GiftGeniusWidget() {
  return <h1>GiftGenius przez tunel 🚇</h1>;
}

Po zapisaniu pliku:

1. Poczekaj, aż Next.js wykona fast refresh,
2. Wejdź do sekcji ChatGPT, w której dodawałeś swoją aplikację, i odśwież ją.
3. Otwórz/odśwież sesję z App w ChatGPT
4. Napisz nowe zapytanie do ChatGPT z prośbą o wyświetlenie twojego widżetu
5. Upewnij się, że nowy tekst nagłówka widać już wewnątrz ChatGPT.

To właśnie mały moment prawdy: przed chwilą zmieniłeś kod na swojej maszynie i ta zmiana pojawiła się w chmurowym interfejsie ChatGPT dzięki tunelowi.

9. Kilka słów o bezpieczeństwie i „co dokładnie wystawiłeś na zewnątrz”

Każdy tunel to nie zabawka, lecz prawdziwe publiczne wejście do twojej maszyny. W naszym scenariuszu edukacyjnym przekazujemy tylko localhost:3000, gdzie działa aplikacja Next.js. To względnie bezpieczne, jeśli:

• ten port nie jest używany do niczego innego;
• nie masz „aplikacji‑potwora”, do której z jakiegoś powodu wbudowano panel admina bazy, phpMyAdmin i jeszcze cztery serwisy demo.

Kilka ważnych praktycznych zasad.

Tunel to narzędzie deweloperskie, a nie produkcyjny system. Świadomie używamy go w Dev Mode, a nie dla prawdziwych użytkowników i na pewno nie do przyjmowania płatności.

Staraj się nie uruchamiać na tym samym porcie (3000) żadnych paneli administracyjnych, baz bez haseł i podobnych rzeczy. Wszystko, co odpowiada na tym porcie, staje się widoczne z internetu, dopóki tunel żyje.

Nie rozsyłaj swojego URL trycloudflare.com gdzie popadnie. Tak, prawdopodobieństwo, że ktoś zacznie go aktywnie skanować, gdy robisz projekt edukacyjny, jest niewielkie. Ale nawyk „link do serwera dev wysyłamy gdziekolwiek” w produkcji może się zemścić.

Później, gdy przejdziemy do tematów o Vercel i środowisku produkcyjnym, będziemy używać normalnego hostingu ze stałymi domenami i bezpieczeństwem produkcyjnym, a tunel pozostanie wyłącznie narzędziem deweloperskim.

10. Typowe błędy przy pracy z lokalnym uruchomieniem i tunelem

Mamy już uruchomiony lokalny Next.js, działający tunel HTTPS i podłączony Dev Mode w ChatGPT. Na koniec — kilka typowych błędów, które niemal każdy popełnia na początku, oraz jak je szybko diagnozować.

Błąd nr 1: próba użycia http://localhost:3000 bezpośrednio w ChatGPT.
Czasem początkujący deweloperzy po prostu kopiują ten URL do konfiguracji Dev Mode i dziwią się, dlaczego ChatGPT pisze, że nie może dotrzeć do App. Przypomnę: localhost to „ja sam” dla tego, kto wykonuje żądanie. Dla ChatGPT to serwery OpenAI, a nie twój laptop. Nie zobaczysz przy tym żadnych logów u siebie, ponieważ żądania w ogóle nie docierają do twojej maszyny.

Błąd nr 2: uruchomienie tunelu do nieistniejącego lub złego portu.
Częsty scenariusz: kiedyś dawno uruchamiałeś npm run dev na porcie 3000, serwer już padł, ale w drugim terminalu z przyzwyczajenia uruchamiasz cloudflared tunnel --url http://localhost:3000. Cloudflare wydaje ładną domenę HTTPS, ale po otwarciu — błąd. Diagnoza jest prosta: lokalny serwer nie żyje. Zawsze najpierw sprawdzaj http://localhost:3000 w przeglądarce, a dopiero potem włączaj tunel.

Błąd nr 3: pomylenie http:// i https:// przy starcie tunelu.
Tunel sam zapewnia ci HTTPS na zewnątrz, ale do lokalnego serwera trzeba łączyć się przez HTTP, np. http://localhost:3000. Próba wskazania https://localhost:3000 często prowadzi do dziwnych błędów TLS w środku lub po prostu do niedostępności. Pamiętaj: HTTPS — na zewnątrz, HTTP — do środka.

Błąd nr 4: zamknięty terminal z tunelem podczas aktywnych testów w ChatGPT.
Kolejny klasyczny przypadek: wszystko skonfigurowałeś, App działa w ChatGPT, po czym przypadkowo zamykasz okno terminala z cloudflared. Po 10 minutach wracasz do ChatGPT — i widzisz „App unavailable”. Powód jest prosty: URL pozostał w ustawieniach App, ale sam tunel jest wyłączony. Zapamiętaj prostą zasadę: dopóki testujesz App w Dev Mode, obok zawsze musi działać terminal z tunelem.

Błąd nr 5: nieświadome użycie nowego URL po ponownym uruchomieniu tunelu.
W trybie quick tunnel Cloudflare przy każdym uruchomieniu przydziela nowy *.trycloudflare.com. Jeśli zatrzymałeś i ponownie uruchomiłeś cloudflared, a w ChatGPT nadal wskazany jest stary URL, ChatGPT będzie grzecznie tam chodzić i dostawać timeouty albo cudzy serwis. Po zmianie URL tunelu zawsze aktualizuj go w ustawieniach Dev Mode. Później porozmawiamy o tym, jak zrobić stabilną domenę deweloperską, żeby nie gonić za adresami URL.

Błąd nr 6: przekierowanie dodatkowych lub niebezpiecznych usług na ten sam port.
Czasem deweloperzy dla wygody uruchamiają na porcie 3000 nie tylko Next.js, ale i różne „narzędzia pomocnicze”: panel debug, eksperymentalne API bez autoryzacji i tak dalej. Gdy tylko przekierujesz ten port przez tunel, wszystko to staje się dostępne z zewnątrz. W projekcie edukacyjnym być może nic strasznego się nie wydarzy, ale taki nawyk w realnych projektach mocno zwiększa ryzyko wycieków i włamań. Zawsze pamiętaj: wszystko, co odpowiada na porcie wskazanym w tunelu, patrzy w internet.