Документация Wrabbit

Что такое Wrabbit

Wrabbit — клиент, а не VPN-сервис. У него нет собственных серверов и он не продаёт доступ. Вы добавляете свои vless://, trojan://, ss:// или ссылку на подписку — ключи и конфигурации хранятся только на устройстве.

• Ядро — Xray-core, протоколы VLESS, Trojan, Shadowsocks.
• Платформы: iPhone / iPad (iOS 16 и новее) и Mac (macOS 13 и новее) — одно приложение, одинаковые конфиги и подписки.
• Гибкая маршрутизация по спискам IP и авто-выбор сервера.
• Совместимость с подписками панелей (Remnawave и совместимых) — без аккаунта и регистрации.

Быстрый старт

• Установите Wrabbit из App Store: iPhone / iPad (iOS 16 и новее) или Mac (macOS 13 и новее).
• Нажмите «+» и добавьте конфигурацию: вставьте ссылку из буфера, отсканируйте QR-код или вставьте URL подписки. Формат определяется автоматически.
• Выберите сервер или режим «Авто» и нажмите «Подключить». При первом подключении iOS или macOS попросит разрешить VPN-профиль.

macOS

• Тот же клиент в Mac App Store (Mac Catalyst): импорт, подписки, авто-режим и маршрутизация работают так же, как на iPhone.
• В строке меню — иконка Wrabbit: быстрое подключение/отключение, статус, открыть окно, настройки и выход — без разворачивания приложения.
• QR-код сканируется камерой Mac (при первом использовании система запросит разрешение; текст запроса локализован под язык интерфейса).

Если подписка перестала отдавать серверы (истёк срок или исчерпан трафик), в карточке появится баннер и кнопка «Продлить» — данные о доступе берутся из ответа подписки, см. раздел «Подписки для провайдеров».

Импорт конфигов и подписок

Поддерживаемые форматы

Способы добавления

• Вставка из буфера обмена или в текстовое поле импорта.
• Сканирование QR-кода камерой.
• Ручной редактор конфигурации (VLESS / Trojan / Shadowsocks).

Клиент сам различает: одиночная http(s)://-ссылка без переносов строк → подписка; одиночная vless:// → отдельный сервер; многострочный текст или trojan:///ss:// → массовый разбор.

Обновление подписки

• Запрос идёт с User-Agent Wrabbit и без кеша (Cache-Control: no-cache), таймаут 20 секунд.
• Успешный ответ полностью заменяет список серверов подписки; ручной выбор сохраняется, если тот же сервер остался.
• Сетевые ошибки и коды 4xx/5xx старый список не трогают — показывается тост «Не удалось обновить».
• Авто-обновление — раз в сутки, глобальный тумблер в настройках. Заголовок интервала обновления из ответа подписки сейчас не учитывается.

Протоколы и транспорты

Для VLESS+REALITY нужны параметры pbk и sni (опционально sid, flow, fp, servicename). Для xHTTP/CDN — path и sni/host. Флоу: none или xtls-rprx-vision.

Маршрутизация

По умолчанию весь трафик идёт через туннель. Локальные/частные сети исключаются автоматически. Дополнительно можно вывести выбранные адреса напрямую, мимо туннеля (split-tunnel по IP).

Списки маршрутизации

• Формат — IPv4 CIDR (одиночный IP трактуется как /32). Разделители: перенос строки, запятая, пробел или ;.
• Списки добавляются текстом или по ссылке (обычный текстовый файл) и обновляются по этой ссылке.
• Для русской локали один раз подсевается готовый пресет RU-зоны; маршрутизация включается тумблером.

Доменная маршрутизация из подписки (стандарт Happ)

Провайдер может доставить правила маршрутизации прямо с подпиской — заголовком routing (тот же формат, что у Happ: happ://routing/onadd/<base64-json>). Wrabbit применяет DirectSites/ProxySites/BlockSites (домены) и DirectIp/ProxyIp/BlockIp (CIDR). Доменные правила работают за счёт sniffing'а соединений. Управление и состав — в Настройки → Маршрутизация доменов.

Авто-режим и выбор сервера

В режиме «Авто» перед подключением клиент пингует серверы группы через прокси (поднимает эфемерный Xray и проверяет доступность), затем выбирает быстрейший живой сервер.

Серверам можно задать роль: обычные (direct) — быстрые прямые серверы, и особые (wl) — резервные серверы для авто-режима. Приоритет — быстрейший живой обычный сервер; если таких нет, клиент берёт особый. На iPhone и Mac при нескольких серверах туннель умеет сам перезапускаться и переключаться между ними при просадке связи.

Для хостов с несколькими edge-входами (балансировщик настроен в панели) Wrabbit дополнительно подтягивает ту же подписку в формате xray-json (<url>/json) и использует нативный пул балансировки — паритет с Happ. Если /json недоступен или подписка чужая, клиент просто работает с одиночным выходом. Отдельной настройки на стороне провайдера не требуется.

Подписки для провайдеров

Wrabbit читает метаданные подписки двумя каналами: через HTTP-заголовки ответа (приоритетный источник) и, как фолбэк, через строку в теле подписки с префиксом # (например #wrab-mode: auto-only). Заголовок всегда важнее строки тела.

wrab-zone — роль сервера (в самой ссылке)

Роль сервера в авто-режиме можно задать явно — query-параметром в vless://: wrab-zone=direct (обычный) или wrab-zone=wl (особый/резервный). Роль также распознаётся по метке в названии сервера (например, WL). Без метки сервер считается обычным (direct).

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Profile-Title: base64:V3JhYg==
Subscription-Userinfo: upload=0; download=0; total=0; expire=1788000000
wrab-mode: auto-only

vless://uuid@nl1.example.com:443?type=grpc&security=reality&pbk=KEY&sni=cloudflare.com&sid=ab&wrab-zone=direct#NL-1
vless://uuid@cdn.example.com:443?type=xhttp&security=tls&sni=edge.example.com&path=/xh&host=edge.example.com&wrab-zone=wl#NL-1 CDN

Истёкшая или отключённая подписка

Если подписка перестала быть активной, панель отдаёт HTTP 200 с метаданными, но без серверов. Wrabbit считает это сигналом «доступа сейчас нет» (не ошибкой): серверы убираются, показывается баннер и кнопка продления (ведёт на Support-Url), активный туннель на исчезнувшем сервере отключается. Поле восстанавливается при следующем обновлении, когда серверы снова появятся.

Лицензирование провайдеров (premium-интеграция)

Wrabbit — нейтральный бесплатный клиент: оплату с пользователей мы не берём, в приложении нет платных функций. Часть возможностей интеграции — premium и доступна провайдерам по лицензии (B2B, вне приложения). Это и есть монетизация клиента: платит провайдер за расширенную интеграцию, конечный пользователь — никогда.

Что бесплатно, а что по лицензии

Как это работает

Лицензия — это подписанный токен, привязанный к домену вашей подписки и сроку действия. Вы кладёте его в заголовок ответа подписки wrab-license (или строкой #wrab-license: в теле — для статических файлов). Клиент проверяет подпись офлайн встроенным ключом (Ed25519) — к нашим серверам он при этом не обращается. Если токен валиден, не истёк, а его домен совпадает с host вашей подписки — соответствующие premium-возможности включаются. Нет токена или он невалиден — эти возможности просто выключены, остальная подписка работает как обычно.

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Profile-Title: base64:V3JhYg==
Subscription-Userinfo: upload=0; download=0; total=0; expire=1788000000
wrab-logo: https://cdn.example.com/logo.png
Announce: base64:0J/RgNC40LLQtdGCIQ==
Support-Url: https://t.me/example_support
hide-settings: 1
routing: happ://routing/onadd/<base64-json>
wrab-license: v1.<base64url(payload)>.<base64url(sig)>

vless://uuid@nl1.example.com:443?type=grpc&security=reality&pbk=KEY&sni=cloudflare.com#NL-1

Формат токена

Токен: v1.<base64url(payload)>.<base64url(подпись Ed25519)>. payload — компактный JSON: dom (домен подписки), feat (массив фич — brand/hide/routing), exp (Unix-срок действия), kid (идентификатор ключа). Подпись считается над строкой v1.<base64url(payload)>. Выпускаем токены только мы: подделать подпись, имея лишь публичный ключ внутри клиента, нельзя.

Как получить лицензию

Self-serve-кабинета пока нет — лицензии выдаём вручную. Напишите нам (см. Поддержку): пришлите домен(ы) вашей подписки и нужный набор фич — мы выпустим токен на согласованный срок. Продление и отзыв — на нашей стороне.

Интеграция с Remnawave

Всё настраивается штатными средствами панели, без форков. Метки доставляются тремя способами:

• Глобально по клиенту — Subscription Response Rules: правило с условием user-agent CONTAINS wrabbit и заголовком, например wrab-mode: auto-only. Прочих клиентов правило не задевает.
• Точечно per-user / по группе — External Squads: поле responseHeaders, например { "wrab-mode": "auto-only" }, назначается выбранным пользователям.
• Роль сервера — меткой в названии (например, WL) или параметром wrab-zone в самой ссылке.

Брендинг в Remnawave: Announce ← happAnnounce, Support-Url ← supportLink (оба в subscription-settings); Profile-Web-Page-Url и wrab-logo ← customResponseHeaders или responseHeaders External Squad.

Доменная маршрутизация: заголовок routing берётся из Subscription Settings → Happ Routing (happRouting). Профиль настраивается в конструкторе на routing.happ.su и доставляется одной строкой — один и тот же профиль применяют и Happ, и Wrabbit (Wrabbit — явные домены/CIDR, без гео-категорий).

Приватность и устройство

Wrabbit не ведёт логи трафика и не передаёт конфигурации третьим сторонам. При запросе подписки по умолчанию отправляются идентификатор устройства (HWID) и модель в заголовках x-hwid, x-device-os, x-ver-os, x-device-model — это нужно для корректного учёта устройств в панели. Отправку HWID можно отключить в настройках.

• Платформы: iPhone / iPad (iOS 16 и новее) и Mac (macOS 13 и новее). Туннель — Packet Tunnel / Network Extension на обеих платформах.
• На Mac — виджет в строке меню для быстрого управления VPN без открытия окна.
• Без аналитики и трекеров; собираются только обезличенные отчёты о сбоях.
• Локализация: русский и английский (плюс системный язык). Запросы разрешений ОС (камера, VPN) показываются на языке интерфейса приложения.

Дополнительные функции

• Защита при разрыве (kill-switch) и автоподключение (on-demand).
• macOS: виджет в строке меню — подключение/отключение, статус, открыть окно и настройки.
• Статистика трафика сессии и пинг серверов через прокси.
• Импорт и экспорт по QR-коду, копирование и шаринг ссылок.
• Локальное редактирование конфигураций (если не скрыто провайдером).
• Фрагментация TLS ClientHello для CDN-серверов — опция совместимости соединения (глобальный тумблер и параметр fragment в ссылке).
• Журнал туннеля и логи Xray с экспортом для диагностики.

Чек-лист совместимости

• Возьмите ссылку подписки из панели и проверьте её в другом клиенте (например Happ) — wrab-* поля не должны ломать разбор.
• Откройте подписку в Wrabbit без wrab-mode — обычный список серверов и «Авто».
• Добавьте wrab-mode: auto-only — должна остаться только строка «Авто», серверы и пинги скрыты.
• Проверьте роли серверов: «Авто» предпочитает обычный (direct), при недоступности берёт особый (wl).
• Сравните пинг «via Proxy» в Wrabbit и Happ — порядок величины должен совпадать.
• Лицензия: без wrab-license брендинг/скрытие/роутинг выключены (это ожидаемо). С валидным токеном на ваш домен — включаются. Если домен в токене не совпадает с host подписки или токен истёк — фичи останутся выключенными.