ntfy

ntfy — это простой pub-sub сервис уведомлений на основе HTTP. Он работает с бесплатным публичным сервером ntfy.sh или любым собственным экземпляром и поддерживает любой клиент, способный выполнять HTTP-запросы — телефоны, браузеры, скрипты, часы.

ntfy отлично подходит в качестве лёгкого push-канала для VibeOS: подпишитесь на топик через мобильное приложение ntfy, отправляйте сообщения в топик для общения с агентом и получайте ответы на телефон.

Выполните vibeos gateway setup и выберите ntfy для пошаговой настройки.

Предварительные требования

• Имя топика (любая уникальная строка — подойдёт vibeos-myname-2026)
• Установленное мобильное приложение ntfy, подписанное на этот топик
• Опционально: собственный сервер ntfy или токен учётной записи ntfy.sh для приватных/зарезервированных топиков

Всё. Никаких SDK, демонов или Node.js. Адаптер использует httpx, который уже является зависимостью VibeOS.

Настройка VibeOS

Через мастер настройки

vibeos gateway setup

Выберите ntfy и следуйте инструкциям.

Через переменные окружения

Добавьте их в ~/.vibeos/.env:

NTFY_TOPIC=vibeos-myname-2026
NTFY_ALLOWED_USERS=vibeos-myname-2026
NTFY_HOME_CHANNEL=vibeos-myname-2026

Переменная	Обязательная	Описание
NTFY_TOPIC	Да	Топик для подписки (входящие сообщения)
NTFY_SERVER_URL	Опционально	URL сервера (по умолчанию: https://ntfy.sh) — укажите собственный сервер ntfy для приватности
NTFY_TOKEN	Опционально	Bearer-токен (например, tk_xyz) или user:pass для Basic-аутентификации
NTFY_PUBLISH_TOPIC	Опционально	Другой топик для исходящих ответов (по умолчанию — NTFY_TOPIC)
NTFY_MARKDOWN	Опционально	Установите true, чтобы отправлять ответы с заголовком X-Markdown: true
NTFY_ALLOWED_USERS	Рекомендуется	Разделённые запятыми имена топиков, которым разрешён доступ (рассматриваются как ID пользователей; см. ниже)
NTFY_ALLOW_ALL_USERS	Опционально	Установите true, чтобы разрешить всех отправителей — безопасно только для приватных топиков с токенами на чтение
NTFY_HOME_CHANNEL	Опционально	Топик по умолчанию для доставки cron-задач и уведомлений
NTFY_HOME_CHANNEL_NAME	Опционально	Человеческое название домашнего канала

Модель идентификации — прочитайте перед развёртыванием

У ntfy нет нативной аутентификации пользователей. Поле title в опубликованном сообщении контролируется отправителем и может быть любым. Адаптер VibeOS НЕ использует title для авторизации — это позволило бы любому отправителю, знающему топик, подделать разрешённого пользователя.

Вместо этого имя топика само является идентификатором. Каждое сообщение, опубликованное в топике, рассматривается как исходящее от одного логического пользователя (топика). Поэтому NTFY_ALLOWED_USERS обычно содержит только само имя топика — одноэлементный белый список, управляющий доступом ко всему каналу.

Это означает, что любой, кто знает топик, может общаться с агентом. Чтобы создать реальную границу доверия:

• Запустите собственный сервер ntfy и защитите топик с помощью контроля доступа. Только авторизованные клиенты с токеном на чтение/запись смогут публиковать сообщения.
• Или используйте приватный топик на ntfy.sh (зарезервированные топики требуют учётной записи) и защитите его с помощью NTFY_TOKEN.
• Или выберите длинное, непредсказуемое имя топика (vibeos-7d4f9c8b-2026) и рассматривайте его как общий секрет. Это самый простой вариант, но имя топика может быть раскрыто через логи или скриншоты.

В любом случае не передавайте через ntfy конфиденциальные данные, если только топик не защищён контролем доступа.

Быстрый старт — общайтесь с агентом с телефона

1. Выберите имя топика: vibeos-myname-2026
2. На телефоне: установите приложение ntfy, нажмите +, введите vibeos-myname-2026
3. На хосте:

   echo 'NTFY_TOPIC=vibeos-myname-2026' >> ~/.vibeos/.env
   echo 'NTFY_ALLOWED_USERS=vibeos-myname-2026' >> ~/.vibeos/.env
   vibeos gateway restart

4. Из приложения ntfy отправьте сообщение в топик. Ответ агента придёт как push-уведомление.

Использование ntfy с cron-задачами

После установки NTFY_HOME_CHANNEL cron-задачи могут доставлять уведомления через ntfy:

cronjob(
    action="create",
    schedule="every 1h",
    deliver="ntfy",          # использует NTFY_HOME_CHANNEL
    prompt="Проверить оповещения и подвести итог."
)

Или явно указать конкретный топик:

send_message(target="ntfy:alerts-channel", message="Готово!")

Это работает даже когда cron выполняется вне процесса шлюза — плагин регистрирует standalone_sender_fn, который открывает собственное HTTP-соединение.

Собственный сервер ntfy

Если вы хотите полный контроль:

# Docker
docker run -p 80:80 -it binwiederhier/ntfy serve

# Native
go install heckel.io/ntfy/v2@latest
ntfy serve

Затем укажите VibeOS на него:

NTFY_SERVER_URL=https://ntfy.mydomain.com
NTFY_TOPIC=vibeos
NTFY_TOKEN=tk_abc123  # если настроен контроль доступа

Собственный сервер даёт вам контроль доступа к топикам, политики сохранения сообщений, вложения и emoji-теги. Подробнее в документации сервера ntfy.

Форматирование Markdown

Клиенты ntfy отображают Markdown, когда издатель устанавливает заголовок X-Markdown: true. Чтобы включить это для исходящих ответов VibeOS:

NTFY_MARKDOWN=true

Или в config.yaml:

platforms:
  ntfy:
    extra:
      markdown: true

Мобильное приложение поддерживает подмножество CommonMark — жирный текст, курсив, списки, ссылки, блоки кода. Точный набор см. в документации ntfy по Markdown.

Только исходящие уведомления (без входящих)

Если вы хотите, чтобы VibeOS только отправлял уведомления в ntfy (сводки cron, оповещения) и никогда не принимал сообщения обратно, установите NTFY_TOPIC и NTFY_PUBLISH_TOPIC в одно значение и полностью пропустите NTFY_ALLOWED_USERS. Без белого списка агент никогда не отвечает на входящие сообщения — ваш телефон получает push-уведомления, но диалог остаётся односторонним.

Ограничения

• Размер сообщения: ntfy ограничивает тело сообщения 4096 символами. VibeOS обрезает его с предупреждением при превышении.
• Нет индикаторов набора текста: протокол не поддерживает их; send_typing не выполняет никаких действий.
• Нет тредов или вложений: ntfy — это простые push-уведомления. Длинные ответы остаются в теле сообщения, без разветвления по тредам.
• Нет нативной идентификации пользователей: см. раздел о модели идентификации выше.

Устранение неполадок

Ошибка аутентификации / 401 — NTFY_TOKEN неверен, или токен не имеет прав на публикацию/подписку в этом топике. Адаптер останавливает цикл переподключения при 401, и статус выполнения шлюза покажет fatal: ntfy_unauthorized. Исправьте токен и перезапустите шлюз.

Топик не найден / 404 — NTFY_TOPIC не существует на настроенном сервере. Для ntfy.sh топики создаются автоматически при первой публикации, поэтому 404 означает, что вы указали на собственный сервер, на котором топик не подготовлен. Адаптер останавливает цикл переподключения с fatal: ntfy_topic_not_found.

Подключено, но нет сообщений — Проверьте, что NTFY_ALLOWED_USERS включает само имя топика. В модели идентификации ntfy топик И является пользователем; пустой белый список отклоняет всё.

Переподключение каждые 60 секунд — По умолчанию keepalive потока составляет 55 секунд; у ntfy могут быть периодические проблемы с сетью. Адаптер применяет экспоненциальную задержку (2 → 5 → 10 → 30 → 60 секунд) и сбрасывает её на 0, когда поток остаётся активным ≥60 секунд.