Локальний запуск, HTTPS‑тунель і доступність для ChatGPT

1. localhost — це лише для вас, а не для ChatGPT

Почнімо з головної «пастки» цього модуля. Ви відкриваєте http://localhost:3000 у браузері — і все чудово працює: Next.js запускається, віджет відображається. Здається логічним: «Раз у мене є URL, то просто передамо його ChatGPT».

Проблема в тому, що localhost — це не «магічний домен моєї машини в інтернеті». Це спеціальна назва, яка завжди вказує на ту саму машину, де запущено браузер або клієнт. Інакше кажучи, ваш ноутбук звертається сам до себе.

Сервери OpenAI, на яких працює ChatGPT, теж уміють звертатися до localhost… але до власного — усередині дата‑центру. А ваш Next.js «схований» за домашнім маршрутизатором, NAT і, можливо, корпоративним VPN.

У цій лекції ми:

• розберемося, чому localhost недоступний для ChatGPT;
• налаштуємо HTTPS‑тунель через cloudflared від localhost:3000 до публічного URL;
• підʼєднаємо цей URL у ChatGPT Dev Mode;
• перевіримо ланцюжок «код → тунель → ChatGPT» на простій зміні у віджеті та обговоримо типові пастки.

Звідси випливають два прості факти:

1. ChatGPT не знає, де саме розташований ваш ноутбук.
2. Навіть якби й знав, напряму дістатися до нього він однаково не може — вхідні зʼєднання закриті.

Крім того, ChatGPT принципово працює лише з публічними HTTPS‑ендпойнтами (точками входу): потрібен повноцінний домен і TLS‑сертифікат. З міркувань безпеки сервери OpenAI не звертаються до довільних HTTP‑адрес без шифрування, тож потрібен саме HTTPS‑домен із чинним сертифікатом. Тому просто «прокинути» назовні http://мій‑зовнішній‑IP:3000 — уже не варіант.

Отже, нам потрібен посередник — сервіс, який:

1. працює в інтернеті й має нормальний HTTPS‑домен;
2. уміє безпечно передавати запити з цього домену до вашого localhost:3000.

Це і є HTTPS‑тунель.

2. Що таке HTTPS‑тунель: інтуїтивна модель

Якщо відкинути «страшні» слова, тунель — це сервіс, який дає вам тимчасовий (або постійний) публічний URL і пересилає всі запити звідти на ваш локальний порт. У мережевій термінології це, по суті, зворотний проксі‑сервер (reverse‑proxy), який тримає вихідне зʼєднання з хмарою.

Інтуїтивна аналогія: ви сидите за зачиненими дверима (домашній маршрутизатор), а тунель — це курʼєр, який стоїть зовні з табличкою «усі листи — сюди». За потреби він заходить до вас через «чорний хід» і передає листи вам у руки.

Схема шляху запиту виглядає приблизно так:

sequenceDiagram
    participant ChatGPT as ChatGPT (хмара)
    participant Tunnel as HTTPS‑тунель
(Cloudflare / ngrok)
    participant Dev as Ваш dev‑сервер
(localhost:3000)

    ChatGPT->>Tunnel: HTTPS‑запит до https://xyz.trycloudflare.com
    Tunnel->>Dev: HTTP‑запит до http://localhost:3000
    Dev-->>Tunnel: Відповідь Next.js
    Tunnel-->>ChatGPT: HTTPS‑відповідь

Ключові моменти тут такі.

По‑перше, ініціатором зʼєднання з тунельним сервісом є ви. Утиліта (cloudflared, ngrok тощо) сама встановлює вихідне зʼєднання з хмарою. Це майже завжди дозволено навіть за NAT/фаєрволом.

По‑друге, тунельний сервіс видає вам HTTPS‑домен із чинним сертифікатом, тож не потрібно вручну підіймати самопідписаний TLS.

По‑третє, для ChatGPT ваш застосунок виглядає як звичайний вебсервіс із HTTPS‑доменом. Він навіть «не здогадується», що далі трафік іде до чийогось ноутбука.

3. Які бувають тунелі й що ми оберемо в курсі

В екосистемі веброзробки є кілька популярних рішень для цього завдання:

• ngrok — класика жанру, яка довго була де‑факто стандартом «як показати локальний сервер назовні».
• Cloudflare Tunnel (cloudflared) — сучасне безкоштовне рішення від Cloudflare. Дає домен виду *.trycloudflare.com навіть без реєстрації; за бажання можна привʼязати й власний домен.
• LocalTunnel — мінімум «магії»: просто npm‑пакет, який видає тимчасовий HTTPS‑URL на кшталт https://something.loca.lt.

Усі вони розвʼязують одне й те саме завдання: дати локальному серверу публічний HTTPS‑домен, який підходить для ChatGPT.

Щоб не розпорошувати увагу, як основний інструмент ми візьмемо Cloudflare Tunnel з утилітою cloudflared. Причини прості: для швидких тунелів не потрібен обліковий запис, HTTPS «із коробки», запуск — однією командою.

Водночас, якщо ви вже прихильник ngrok — нічого страшного. Команди будуть трохи іншими, але концепція та сама: ngrok http 3000 замість cloudflared tunnel --url http://localhost:3000.

Щоб було простіше орієнтуватися, зведемо інструменти в невелику таблицю.

https://*.trycloudflare.com

https://*.ngrok.app

https://*.loca.lt

У цій лекції ми зосередимося на Cloudflare Tunnel у режимі «швидкий одноразовий тунель». Цього більш ніж достатньо, щоб «подружити» ваш Next.js із ChatGPT у Dev Mode.

4. Перевіряємо, що локальний Next.js працює

Перш ніж «виносити» щось назовні через тунель, переконайтеся, що локальний сервер справді запущено. Інакше ви відлагоджуватимете тунель, хоча проблема в тому, що Next.js просто не працює.

Нагадаю стандартний порядок:

# з кореня проєкту зі шаблоном Apps SDK
npm install      # якщо ще не робили
npm run dev      # запуск dev-сервера Next.js

Зазвичай Next.js 16 піднімається на http://localhost:3000 (якщо порт не зайнято). У терміналі ви побачите щось на кшталт:

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

Відкрийте в браузері http://localhost:3000 і переконайтеся, що сторінка шаблону відкривається. Це ваша «локальна лабораторія». Якщо тут щось не працює (помилка збірки, TypeScript скаржиться, порт зайнятий), — спершу виправте це, а вже потім переходьте до тунелю.

5. Запускаємо Cloudflare Tunnel: від localhost до публічного HTTPS

Переходимо до найцікавішого: зробимо так, щоб хто завгодно в інтернеті (зокрема ChatGPT) міг відкрити ваш Next.js за HTTPS‑URL.

Встановлення cloudflared

Спосіб встановлення залежить від ОС. Найпростіший шлях для macOS — через Homebrew:

brew install cloudflare/cloudflare/cloudflared

На Windows і Linux можна завантажити готовий бінарник або скористатися менеджером пакетів, як рекомендує документація Cloudflare (посилання є в додаткових матеріалах модуля).

Перевірити встановлення можна командою:

cloudflared --version

Якщо утиліту не знайдено, перевірте PATH або перезапустіть термінал.

Швидкий одноразовий тунель

Наша мета зараз — мінімальний робочий тунель без облікового запису, власного домену й складних конфігурацій. Для цього у cloudflared є режим quick tunnel, який видає URL на домені trycloudflare.com.

Коли у вас запущено npm run dev, виконайте в іншому терміналі:

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

Запамʼятайте просте правило: HTTPS — ззовні, HTTP — усередині. cloudflared сам видає вам зовнішній HTTPS‑домен, але до вашого localhost:3000 він звертається звичайним HTTP.

Після короткого логу ви побачите рядок на кшталт:

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

Цей https://giftgenius-1234.trycloudflare.com — і є нова публічна адреса вашого локального застосунку. Тунель приймає HTTPS‑запити на цей домен і пересилає їх на http://localhost:3000.

Кілька важливих моментів.

По‑перше, термінал із cloudflared має залишатися відкритим, доки потрібен тунель. Щойно ви його закриєте (або натиснете Ctrl+C), тунель зупиниться, а URL перестане працювати.

По‑друге, під час кожного запуску quick tunnel URL може бути новим. Для навчальної розробки це нормально: мета поточного модуля — просто дати ChatGPT доступ до вашого локального Next.js через будь‑яку робочу HTTPS‑адресу. Але це означає, що в ChatGPT Dev Mode іноді доведеться оновлювати URL. У модулі 7 ми повернемося до теми тунелів і налаштуємо повноцінний стабільний dev‑домен, щоб не «бігати» за адресами.

Перевіряємо тунель як звичайний сайт

Перш ніж підʼєднувати все це в ChatGPT, перевіримо, чи тунель узагалі відкривається з інтернету.

1. Відкрийте отриманий https://...trycloudflare.com у браузері.
2. Ви маєте побачити той самий інтерфейс, що й на http://localhost:3000.
3. У консолі, де запущено npm run dev, ви побачите нові запити — тобто Next.js справді обслуговує зовнішнє звернення.

Якщо сторінка не відкривається або показує помилку, спершу перевірте:

• чи запущено npm run dev;
• чи не помилилися ви в локальному URL під час запуску тунелю (http://localhost:3000, а не https:// і не порт 3001);
• чи не блокує щось вихідні зʼєднання (рідко, але трапляється в суворих корпоративних мережах).

6. Підʼєднуємо цей URL у ChatGPT Dev Mode

Тепер у нас є все, щоб зібрати ланцюжок:

ChatGPT (хмара) → ваш HTTPS‑тунель → локальний Next.js.

Інтерфейс Dev Mode ви вже бачили в попередній лекції. Зараз просто повторимо ті самі кроки, але з реальним HTTPS‑URL, а не «теоретичним».

Загальна послідовність дій у ChatGPT така.

Спочатку відкрийте ChatGPT у браузері та перейдіть у розділ для розробників (зазвичай щось на кшталт «Developer», «Apps», «My apps» — конкретні назви можуть змінюватися з оновленням інтерфейсу).

Створіть новий App або відредагуйте вже наявний dev‑App, якщо ви його створювали раніше.

У полі, куди потрібно вставити URL вашого App, вкажіть базову адресу тунелю, наприклад:

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

Точкою входу є наш /route/mcp.ts. Під час підʼєднання ChatGPT почне саме з нього, а далі отримає всю необхідну інформацію. У README шаблону може бути зазначено інший шлях — наприклад, якщо застосунків кілька. Але поки вважаймо, що базовий URL тунелю + /mcp — це саме те, що вам потрібно.

Збережіть конфігурацію App. У цей момент ChatGPT зробить кілька запитів до вашого застосунку через тунель:

• зчитає маніфест App (метадані, інструменти тощо);
• перевірить доступність MCP‑ендпойнта;
• отримає список усіх tools і ресурсів;
• кешуватиме HTML‑код усіх віджетів (!).

Якщо все гаразд, ви побачите свій App у списку dev‑Apps. Якщо щось зламано (нечинний маніфест, сервер не відповідає, тунель зупинився), ChatGPT покаже помилку на кшталт «App unavailable» або щось подібне.

Важливо: цей самий HTTPS‑URL тунелю ChatGPT використовуватиме і для виклику інструментів (MCP), і для завантаження віджета та статики. У наступному розділі розберемо ці дві ролі окремо.

7. Як тепер ходять запити: дві ролі вашого тунелю

Важливо чітко розуміти, що саме ChatGPT робить із цим URL. В архітектурі Apps SDK є дві основні точки входу: MCP‑ендпойнт і UI‑віджет.

Якщо спростити, ланцюжок виглядає так:

flowchart LR
    ChatGPT["ChatGPT (модель)"] 
    subgraph Internet
        Tunnel[HTTPS‑тунель
giftgenius-1234.trycloudflare.com]
    end
    Local["Next.js dev‑сервер http://localhost:3000"]

    ChatGPT -- HTTP(S)-запити до /mcp --> Tunnel
    ChatGPT -- Завантаження iframe /widget --> Tunnel
    Tunnel --> Local

Фактично тунель має дві основні ролі:

• Роль 1: MCP‑ендпойнт (інструменти). Коли модель вирішує викликати інструмент (tool), вона робить HTTP POST на MCP‑ендпойнт (у шаблоні це маршрут app/mcp/route.ts у Next.js) за тим самим доменом тунелю.
• Роль 2: UI‑віджет і статика. Коли модель вирішує показати віджет, вона вбудовує iframe з вашим URL (зазвичай /widget або те, що вказано в маніфесті), і завантаження також іде через тунель.

У цьому сенсі тунель не «для чогось одного». Це єдині двері до вашого локального App: UI, MCP, статика — усе йде через один і той самий публічний HTTPS‑домен.

8. Практика: перевіряємо ланцюжок «код → тунель → ChatGPT»

Щоб переконатися, що все справді працює, а не лише гарно намальовано на схемах, виконайте мінімальний практичний сценарій.

По‑перше, запустіть npm run dev і переконайтеся, що http://localhost:3000 відкривається в браузері.

По‑друге, запустіть cloudflared tunnel --url http://localhost:3000 і отримайте публічний HTTPS‑URL. Перевірте його в іншому браузері або навіть на іншому пристрої (наприклад, на телефоні через мобільний інтернет) — так ви точно переконаєтеся, що запити йдуть через інтернет, а не «крутяться» лише на вашій машині.

По‑третє, відкрийте ChatGPT, перейдіть у Dev Mode й переконайтеся, що ваш App підʼєднано за цим URL. У Composer у чаті ChatGPT виберіть свій App, почніть діалог і подивіться, чи вставляє ChatGPT віджет і чи завантажує ваш інтерфейс.

Щоб наочно побачити, що це саме ваш код, змініть щось зовсім просте у віджеті, наприклад заголовок:

// app/widget/page.tsx (приклад)
'use client';

export default function GiftGeniusWidget() {
  return <h1>GiftGenius через тунель 🚇</h1>;
}

Після збереження файлу:

1. дочекайтеся, поки Next.js виконає fast refresh;
2. зайдіть у розділ ChatGPT, де ви додавали свій App, і оновіть його (refresh);
3. відкрийте або оновіть сесію з App у ChatGPT;
4. надішліть новий запит до ChatGPT із проханням відобразити ваш віджет;
5. переконайтеся, що новий текст заголовка видно вже всередині ChatGPT.

Це і є невеликий момент істини: ви щойно змінили код на своїй машині — і ця зміна відобразилася в хмарному інтерфейсі ChatGPT через тунель.

9. Трохи про безпеку й «що саме ви відкрили назовні»

Будь‑який тунель — це не іграшка, а реальний публічний вхід до вашої машини. У нашому навчальному сценарії ми «прокидаємо» лише localhost:3000, де працює Next.js‑застосунок. Це відносно безпечно, якщо:

• цей порт не використовується ні для чого іншого;
• у вас немає «застосунку‑монстра», у який чомусь вбудована адмінка бази даних, phpMyAdmin і ще кілька демосервісів.

Кілька важливих практичних правил.

Тунель — це інструмент розробки, а не «бойовий» продакшн. Ми свідомо використовуємо його в Dev Mode, а не для реальних користувачів і вже точно не для приймання платежів.

Намагайтеся не запускати на цьому ж порту (3000) жодних адміністративних панелей, баз без паролів та подібних речей. Усе, що відповідає на цьому порту, стає видимим з інтернету, доки тунель активний.

Не поширюйте свій trycloudflare.com URL будь‑де. Так, імовірність, що хтось почне його активно сканувати, поки ви робите навчальний проєкт, невисока. Але звичка «посилання на dev‑сервер можна надсилати куди завгодно» у продакшні може боляче вдарити.

Пізніше, коли ми дійдемо до теми Vercel і production‑оточення, ми використовуватимемо нормальний хостинг зі сталими доменами та продакшн‑безпекою, а тунель залишиться суто dev‑інструментом.

10. Типові помилки під час роботи з локальним запуском і тунелем

Отже, у нас уже є запущений локальний Next.js, робочий HTTPS‑тунель і підʼєднаний Dev Mode у ChatGPT. Насамкінець — кілька типових помилок, які майже в усіх трапляються на перших ітераціях, і способи швидко їх діагностувати.

Помилка № 1: спроба використати http://localhost:3000 прямо в ChatGPT.
Іноді розробники‑початківці просто копіюють цей URL у налаштування Dev Mode і дивуються, чому ChatGPT пише, що не може підʼєднатися до App. Нагадаю: localhost — це «я сам» для того, хто робить запит. Для ChatGPT це сервери OpenAI, а не ваш ноутбук. Жодних особливих логів ви при цьому в себе не побачите, тому що запити взагалі не доходять до вашої машини.

Помилка № 2: запуск тунелю до неіснуючого або неправильного порту.
Поширений сценарій: ви колись давно запускали npm run dev на 3000‑му порту. Сервер уже зупинився, але в іншому терміналі ви за звичкою запускаєте cloudflared tunnel --url http://localhost:3000. Cloudflare видає вам красивий HTTPS‑домен, але під час відкриття — помилка. Діагноз простий: локальний сервер не працює. Завжди спочатку перевіряйте http://localhost:3000 у браузері, а вже потім вмикайте тунель.

Помилка № 3: плутанина між http:// та https:// під час запуску тунелю.
Тунель сам дає вам HTTPS ззовні, але до локального сервера йому потрібно звертатися через HTTP, наприклад http://localhost:3000. Спроба вказати https://localhost:3000 часто призводить до дивних TLS‑помилок «усередині» або просто до недоступності. Памʼятайте правило: HTTPS — ззовні, HTTP — усередині.

Помилка № 4: закритий термінал із тунелем під час активного тестування в ChatGPT.
Ще один класичний випадок: ви все налаштували, App працює в ChatGPT, а потім випадково закриваєте вікно термінала з cloudflared. За 10 хвилин повертаєтеся в ChatGPT — і бачите «App unavailable». Причина проста: URL лишився в налаштуваннях App, але сам тунель вимкнено. Запамʼятайте правило: доки ви тестуєте App у Dev Mode, поруч має працювати термінал із тунелем.

Помилка № 5: непомічена зміна URL після перезапуску тунелю.
У режимі quick tunnel Cloudflare під час кожного запуску дає новий *.trycloudflare.com. Якщо ви зупинили й знову запустили cloudflared, а в ChatGPT досі вказано старий URL, ChatGPT чесно звертатиметься туди й отримуватиме таймаути або чужий сервіс. Після зміни URL тунелю завжди оновлюйте його в налаштуваннях Dev Mode. Пізніше ми поговоримо про те, як зробити стабільний dev‑домен, щоб не «бігати» за URL‑адресами.

Помилка № 6: «прокидання» зайвих або небезпечних сервісів на той самий порт.
Іноді розробники заради зручності запускають на 3000‑му порту не лише Next.js, а й різні «службові» речі: debug‑панель, експериментальний API без авторизації тощо. Щойно ви відкриваєте цей порт через тунель, усе це стає доступним ззовні. Для навчального проєкту, можливо, нічого страшного не станеться, але така звичка в реальних проєктах різко підвищує ризик витоків і зламів. Тримайте в голові: усе, що відповідає на порту, вказаному в тунелі, виходить в інтернет.