демо-стенд · підготовлено під проєкт «Підключити аі-агента до regxa.com»

Hermes на вашому VPS: маршрут розгортання і панель приймання

Стенд показує не розмову з ботом, а як саме закриваються ваші 4 пункти приймання — ZIP у проєкті Codex/Claude Code, Hermes живе на сервері й відповідає в Telegram, Notion підключений і знання перенесені з перевіркою. Кожен пункт нижче має команду перевірки й очікуваний вивід, щоб приймання було фактом, а не словом «готово».

01Ваші 4 пункти приймання — як панель, а не як обіцянка

Це і є те, за чим ви приймаєте роботу. Натисніть на рядок, щоб позначити пункт — так виглядатиме панель у день здачі.

Приймання проєкту · Hermes / VPS / Telegram / Notion 0 / 4 закрито

VPS обрано й підготовлено Regxa або альтернатива. Ubuntu 24.04 LTS, окремий користувач hermes, SSH по ключу, автооновлення безпеки, swap. Перевірка: systemctl is-system-running + free -h.

ZIP доданий у проєкт Codex / Claude Code Архів розпакований у робочий репозиторій, структура приведена до вигляду, який ці інструменти читають: корінь проєкту, README, .env.example, файл правил проєкту. Перевірка: інструмент відкриває проєкт і бачить файли агента.

Hermes працює на сервері й відповідає в Telegram Служба systemd з автостартом і перезапуском після падіння/ребуту. Перевірка: systemctl is-active hermes = active, і бот відповідає на /start у вашому чаті.

Notion підключений, знання перенесені, результат перевірено Офіційний Notion API, сторінки вивантажені, розбиті на фрагменти, проіндексовані. Перевірка: питання з бази знань → відповідь у Telegram із посиланням на конкретну сторінку Notion.

Панель — це форма здачі: поки рядок не зелений, пункт не прийнятий. Нічого не «майже готово».

02Крок 1 — VPS: Regxa чи альтернатива, і чому це не питання смаку

У заголовку стоїть Regxa, у тексті — «або вибрати інший VPS». Вибір вирішує одна річ: чи вистачить пам'яті агенту разом з індексом знань Notion. Нижче — мінімум, з якого Hermes не почне падати на індексації, і запас, з яким не доведеться переїжджати через місяць.

Параметр	Мінімум, що працює	Рекомендую	Чому саме так
RAM	2 ГБ + 2 ГБ swap	4 ГБ	Індексація бази знань — пік пам'яті. На 1 ГБ процес вбиває OOM-killer посеред переносу, і це виглядає як «агент зламався».
vCPU	1	2	Один потік тримає Telegram-опитування, другий — довгі запити до моделі. На 1 vCPU бот «залипає» на 10-20 с під час відповіді.
Диск	20 ГБ SSD	40 ГБ SSD	Код + залежності ~3 ГБ, індекс знань росте з обсягом Notion, логи й бекапи — решта.
ОС	Ubuntu 22.04	Ubuntu 24.04 LTS	Свіжий Python з коробки, підтримка до 2029 — не доведеться мігрувати посеред роботи.
Мережа	будь-яка	вихід без блокувань до api.telegram.org та api.notion.com	Це єдина реальна вимога до провайдера. Перевіряю до оплати тарифу, а не після.

Що перевіряю на Regxa до того, як щось ставити: чи відкриті вихідні з'єднання до Telegram і Notion, чи є нормальна консоль на випадок, якщо SSH ляже, і чи не ріже провайдер довгі HTTPS-сесії. Якщо хоч один пункт не тримається — кажу прямо і пропоную альтернативу з таким самим ціником, а не мовчки ставлю на те, що потім гальмуватиме.

03Крок 2 — Hermes на сервері: служба, а не «запущено в терміналі»

Головна різниця між «працює» і «працює завтра вранці» — чи піднімається агент сам після перезавантаження сервера. Тому Hermes ставиться як служба systemd під окремим користувачем, з обмеженими правами й автоперезапуском.

# /etc/systemd/system/hermes.service — фрагмент, який і дає автостарт
[Service]
User=hermes
WorkingDirectory=/opt/hermes
EnvironmentFile=/opt/hermes/.env      # ключі лежать тут, а не в коді
ExecStart=/opt/hermes/.venv/bin/python -m hermes
Restart=always                        # впав — піднявся сам
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

# приймання цього кроку — дві команди, обидві при вас
$ systemctl is-active hermes
active
$ sudo reboot   # і через хвилину:
$ systemctl is-active hermes
active                                  # ось це і є «працює на сервері»

Ключі й доступи

Токен бота, ключ Notion і ключ моделі — у файлі .env з правами 600, доступний лише користувачу hermes. У репозиторій потрапляє тільки .env.example без значень. Жоден ключ не опиняється в історії git і в логах.

Логи, які можна читати

Один рядок на запит: хто спитав, скільки відповідь готувалася, які сторінки Notion підтяглися. journalctl -u hermes -f — і видно, що відбувається. Ротація увімкнена, диск не забивається.

04Крок 3 — Telegram: чому опитування, а не webhook

Webhook вимагає публічного домену й дійсного TLS-сертифіката на вашому VPS. Це зайвий вузол, який ламається тихо: сертифікат протермінувався — бот просто мовчить, і ніхто не розуміє чому. Для одного агента на одному сервері правильний вибір — long polling: жодного домену, жодного сертифіката, жодного відкритого порту назовні.

# перевірка, що бот справді ваш і справді живий
$ curl -s "https://api.telegram.org/bot$TG_TOKEN/getMe" | jq '.result.username'
"your_hermes_bot"

# перевірка, що webhook НЕ висить (інакше polling мовчатиме — класична пастка)
$ curl -s "https://api.telegram.org/bot$TG_TOKEN/getWebhookInfo" | jq '.result.url'
""

# у чаті:
you  → /start
bot  ← Hermes на зв'язку. База знань: 128 сторінок Notion, оновлено 5 хв тому.

Окремо закриваю дві речі, які зазвичай спливають уже після здачі:

Хто має право писати боту. За замовчуванням — тільки ваші Telegram-ID. Інакше чужа людина, що знайшла бота пошуком, витрачає ваші токени моделі.
Довгі відповіді. Telegram ріже повідомлення на 4096 символах. Відповідь розбивається коректно, а не обривається на півслові.

05Крок 4 — Notion: перенести знання так, щоб агент на них справді спирався

«Підключити Notion» і «агент відповідає з вашої бази» — це дві різні роботи. Перше — ключ інтеграції. Друге — щоб сторінки були розібрані, порізані на фрагменти й проіндексовані, інакше агент бачить базу, але відповідає з голови.

1. Доступ

Внутрішня інтеграція Notion, ви вручну ділитеся з нею потрібними сторінками. Агент бачить рівно те, що ви дали — не весь воркспейс.

2. Перенесення

Сторінки й бази вивантажуються у markdown зі збереженням заголовків, таблиць і вкладеності. Фрагменти ~800 символів з перекриттям, щоб не різати думку навпіл.

3. Оновлення

Синхронізація за розкладом (раз на годину) — змінили сторінку в Notion, агент через годину відповідає вже по-новому. Без ручного перезапуску.

# приймання цього кроку — не «підключено», а відповідь із посиланням
you  → Які умови повернення в нашому тарифі Pro?
bot  ← Повернення протягом 14 днів з моменту оплати, без пояснення причин.
       Після 14 днів — пропорційно невикористаному періоду.
       Джерело: Notion → «Тарифи та біллінг» → розділ «Повернення»
       https://www.notion.so/...

# якщо відповіді в базі немає — агент каже це прямо, а не вигадує
you  → Скільки коштує впровадження в Бразилії?
bot  ← У базі знань такого немає. Найближче: «Регіональні тарифи» — Бразилія там не згадана.

Це та сама «перевірка результату» з вашого ТЗ. Я беру у вас 10 контрольних запитань, відповіді на які точно є в Notion, і проганяю їх усі. Здача — таблиця: питання → відповідь агента → сторінка-джерело. Усі 10 мають попасти в правильну сторінку. Не попадають — донастроюю індекс, а не пояснюю, чому так буває.

06Крок 5 — ZIP у проєкті Codex / Claude Code

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

Що роблю	Навіщо
Розпаковую ZIP у чистий репозиторій з `git init` і першим комітом	З'являється історія: видно, що змінилося, і є куди відкотитися.
`.gitignore` на `.env`, `.venv`, індекс знань, логи	Ключі й сміття не потрапляють у репозиторій — найчастіша причина злитого токена.
Файл правил проєкту в корені	Коротко: що це за агент, як запускати, де конфіг, чого не чіпати. Саме цей файл інструменти читають першим.
`README` українською: запуск, зупинка, оновлення знань, перегляд логів	Щоб ви керували агентом самі, без мене.
`.env.example` з переліком змінних без значень	Видно, які ключі потрібні, і жоден справжній не лежить у коді.

07Що передаю в кінці

Сервер, який переживає ребут

Служба з автостартом, обмежені права, увімкнена ротація логів, налаштовані автооновлення безпеки.

Таблиця приймання

10 контрольних запитань → відповідь агента → сторінка Notion-джерело. Плюс вивід усіх команд перевірки з цього стенда.

Репозиторій, що відкривається в Codex/Claude Code

Структура, правила проєкту, README українською, .env.example.

Інструкція на 1 сторінку

Як перезапустити, як оновити знання, як подивитися логи, що робити, якщо бот замовк. Без мене.

08Чесні межі — щоб не було сюрпризів на здачі

Оплату за VPS і за API моделі робите ви, зі свого рахунку. Я не тримаю ваші платіжні дані й не беру сервер на себе — інакше ви залежите від мене в найгіршому місці.
Доступи ви даєте самі: токен бота від @BotFather, ключ інтеграції Notion, ключ моделі, SSH до VPS. Я нічого не створюю від вашого імені.
Якщо ZIP з Hermes виявиться неробочим сам по собі (не запускається навіть локально) — кажу про це в перший день, а не на сьомий. Лагодження чужого коду поза межами налаштування — це окрема домовленість, і я назву її ціну наперед, до того, як щось робити.
Якість відповідей агента залежить від того, що лежить у Notion. Порожня база — порожні відповіді. На етапі перевірки я покажу, які саме сторінки тягнуться, щоб було видно, де дірка в знаннях, а де в налаштуванні.

09Строк, етапи, ціна

Етап	Що закривається	Коли
1	VPS перевірено й підготовлено, ZIP у репозиторії, проєкт відкривається в Codex/Claude Code	день 1-2
2	Hermes службою, автостарт після ребуту, відповідає в Telegram на `/start`	день 3-4
3	Notion підключено, знання перенесено, прогін 10 контрольних запитань	день 5
4	Таблиця приймання, README, інструкція, ваші правки	день 6-7

7 днів, 25 EUR — рівно бюджет проєкту. У ціну входять правки після перевірки, поки всі 4 пункти вашого чек-листа не стануть зеленими.