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

Что такое Wrabbit

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

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

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

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

macOS

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

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

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

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

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

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

Клиент сам различает: текст, начинающийся с {/[ → Xray JSON; одиночная http(s)://-ссылка без переносов строк и без vless:// в тексте → подписка; vless://, trojan://, ss://, hysteria2:// и hy2:// → отдельные серверы или массовый разбор.

Xray JSON (Remnawave)

Вставьте содержимое <sub_url>/json Remnawave (массив конфигов с remarks) или один конфиг-объект — клиент добавит по серверу на каждую запись с поддерживаемым proxy-outbound. Для VLESS / Trojan / Shadowsocks туннель поднимается из native xray-json записи (outbounds, balancers и цепочки dialerProxy / fragment панели сохраняются); клиент подставляет свой SOCKS-inbound и при наличии Happ-профиля маршрутизации может наложить его domain/DNS-правила. Hysteria2 из xray-json мапится в поля сервера и поднимается отдельным Hy2-ядром — не через native xray-json.

• Поддерживаемые outbound'ы в xray-json: VLESS (REALITY TCP/gRPC, xHTTP и WebSocket за CDN), Trojan, Shadowsocks и Hysteria2 — не только ссылки vless://.
• Подключение (VLESS/Trojan/SS) идёт из native JSON; UI-пинг и авто-выбор берут preferred outbound (или native-outbound probe), чтобы не мерить decoy. Hy2 — отдельное ядро.
• Если сервер уже добавлен по share-ссылке с теми же параметрами и тем же именем (dedupe-ключ), дубль не создаётся — к существующему серверу прикрепляется/обновляется native-конфиг из JSON.
• Для CDN (xHTTP) при native-конфиге клиент может добавить фрагментацию TLS ClientHello поверх конфига панели (per-server fragment= или глобальный тумблер), если в шаблоне ещё нет outbound fragment. На REALITY фрагментация не применяется.

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

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

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

Для VLESS+REALITY в share-ссылке нужны pbk и sni (опционально sid, flow, fp, servicename). Для xHTTP/CDN в share — path и sni/host (алиас типа: splithttp). Типичный flow: none или xtls-rprx-vision (строгой проверки значения нет). VLESS на голом TCP (security=none / пустой security, type=tcp|raw) поддерживается. Подключение из xray-json идёт через нативный JSON панели (без повторной фильтрации транспорта).

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

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

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

• Формат — IPv4 CIDR (одиночный IP трактуется как /32). Разделители: перенос строки, запятая, пробел или ;.
• Списки добавляются текстом или по ссылке (обычный текстовый файл) и обновляются по этой ссылке.
• Каждый набор правил включается тумблером. Отдельный пресет «RU-зона» больше не подсевается: обход РФ приходит из профиля routing подписки (geoip:/geosite:) плюс короткий hot-CDN bypass в Network Extension.

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

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

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

Строка «Авто» в списке серверов появляется, когда в группе ≥2 серверов (или всегда при wrab-mode: auto-only). При холодном старте клиент пингует серверы группы через прокси (эфемерный SOCKS на Xray или Hysteria2, check-URL). Hedged-отбор может завершиться досрочно только на первом живом direct (.ok); быстрый wl сам по себе прогон не обрывает, пока в группе есть direct-кандидаты. Итог: быстрейший живой direct, иначе — wl. Повторный старт по свежему кэшу ранжирования (до ~12 ч) может подключиться без нового пинга.

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

Wrabbit дополнительно подтягивает ту же подписку в формате xray-json (<url>/json) и использует нативные конфиги панели для хостов VLESS/Trojan/SS: routing/DNS шаблона, а для мульти-edge — нативный пул балансировки (DomainStrategy у Wrabbit всегда AsIs). Если /json недоступен или подписка чужая, клиент собирает конфиги из share-ссылок (vless:// / trojan:// / ss:// / hysteria2://), как раньше. Отдельной настройки на стороне провайдера не требуется.

Пинг «via Proxy» и check-URL

• Check-URL: https://cp.cloudflare.com/generate_204 — успех = HTTP 2xx (как у Happ «via Proxy»).
• Подключение — из нативного xray-json; UI-пинг и авто-отбор — по полям preferred outbound / native-outbound probe (не по первому outbound в массиве).
• Цепочки dialerProxy / fragment из нативного JSON учитываются и при пинге — сервер, который «оживает» только через fragment, не забракуется ложно.

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

Wrabbit читает метаданные подписки в первую очередь из HTTP-заголовков ответа. Фолбэк строкой тела с префиксом # есть только у wrab-mode, hide-settings и happ://routing/… (например #wrab-mode: auto-only). Заголовок всегда важнее строки тела. Остальные ключи таблицы — только из заголовков. Если основной URL отдаёт xray-json, body-# не разбирается.

Зоны серверов (direct / wl) и маркер ~

Клиент делит серверы на две логические зоны. Зона не зависит от транспорта — её задаёте вы меткой в названии или параметром в vless://.

• direct — обычный быстрый сервер (по умолчанию).
• wl (whitelist) — резерв для сетей с «белыми списками»; авто уходит на него, когда direct перестал везти данные, и возвращается на direct при оживлении.
• Явный override только в vless://: query wrab-zone=direct или wrab-zone=wl (приоритетнее названия). Синонимы: wl/whitelist/white/cdn/бс/bs и direct/normal/default. В trojan:// / ss:// / hysteria2:// и в xray-json параметр не читается — зона только из названия.
• По названию (remark / #fragment): отдельное слово WL, whitelist, white list, white zone, LTE или БС (регистр не важен) → wl; иначе → direct. БС ловит remark вида [БС-4]. Слово CDN само по себе зоной не является.
• Маркер ~ в любом месте названия — сервер виден для ручного выбора и UI-пинга, но не участвует в авто-отборе и NE-фейловере. Если ~ стоят у всех нод группы, исключение игнорируется. В auto-only список серверов скрыт, поэтому ~ там влияет только на пул авто (пользователь ноду вручную не видит).

Примеры ответа подписки

Обычный список + зоны через wrab-zone (в UI: серверы видны, есть строка «Авто»). Слово CDN в имени — просто подпись; зону задаёт wrab-zone=wl.

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

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 WL
vless://uuid@lab.example.com:443?type=tcp&security=reality&pbk=KEY&sni=www.microsoft.com&sid=cd#~ Lab QUIC

auto-only: в Wrabbit пользователь видит карточку провайдера и одну строку выбора с именем из Profile-Title (не слово «Авто») и подписью про автоподбор. Серверы и пинги скрыты; авто по-прежнему предпочитает direct, затем wl.

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Profile-Title: Wrab
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 WL

Тот же auto-only строкой тела (если заголовки панели недоступны). Заголовок, если есть, важнее.

#wrab-mode: auto-only
#hide-settings: 1
vless://uuid@nl1.example.com:443?type=grpc&security=reality&pbk=KEY&sni=cloudflare.com&sid=ab#NL-1

Фрагментация TLS ClientHello для CDN (только xHTTP+TLS, не REALITY): fragment=1 или полный вид fragment=tlshello,100-200,10-20. Другие клиенты неизвестный ключ игнорируют.

vless://uuid@cdn.example.com:443?type=xhttp&security=tls&sni=edge.example.com&path=/xh&host=edge.example.com&wrab-zone=wl&fragment=1#NL-1 WL

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

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

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

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

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

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

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

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" }, назначается выбранным пользователям.
• Роль сервера — меткой в remark (например суффикс WL или LTE) либо wrab-zone в host-address vless:// (не в trojan/ss/hy2).

Пример responseHeaders External Squad (или customResponseHeaders):

{
  "wrab-mode": "auto-only",
  "wrab-logo": "https://cdn.example.com/logo.png",
  "wrab-license": "v1.<base64url(payload)>.<base64url(sig)>"
}

Брендинг в Remnawave: Announce ← happAnnounce, Support-Url ← supportLink (оба в subscription-settings); Profile-Web-Page-Url ← встроенный тумблер isProfileWebpageUrlEnabled (URL из SUB_PUBLIC_DOMAIN) и/или customResponseHeaders / responseHeaders External Squad; wrab-logo ← только customResponseHeaders или responseHeaders External Squad.

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

Нативные Xray-конфиги: при импорте и обновлении подписки клиент дополнительно запрашивает <sub_url>/json и для каждого сервера сохраняет полный конфиг записи (routing, DNS, балансировщики, burstObservatory). Соединение поднимается из него как есть — панель управляет поведением всех хостов так же, как для Happ, включая одиночные REALITY-серверы, Trojan/SS outbound'ы и мульти-edge балансировку. Если у подписки нет /json-эндпоинта, клиент молча собирает конфиг из ссылок, как раньше.

Preferred outbound и decoy (для провайдеров)

В записи часто несколько outbound'ов (рабочий путь + decoy). Подключение всегда из нативного JSON (балансер/routing панели). UI-пинг и авто-отбор смотрят на preferred outbound — иначе пинг может мерить decoy и показывать «красный» при живом туннеле.

Порядок выбора preferred outbound: routing.balancers[].fallbackTag → tag proxy-wl* / *-wl-* (Liberty) → non-decoy, если в пуле есть *decoy* → указатель из routing.rules (outboundTag / balancerTag) → пул balancer.selector → транспортный кластер (при смеси TLS-stream над Reality) → tag proxy → первый proxy-outbound.

• Рекомендуется: задайте routing.balancers[].fallbackTag на рабочий outbound — это самый надёжный сигнал для UI-пинга.
• Decoy: пометьте decoy в tag (например proxy-decoy-…) или используйте другой транспорт, чем у рабочего пути — тогда клиент не спутает их при выборе полей для пинга.
• Цепочки dialerProxy / fragment в нативном JSON поддерживаются и при пинге (паритет с connect).

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

Wrabbit не ведёт логи трафика и не передаёт конфигурации третьим сторонам. При каждом запросе подписки (и дополнительном запросе <sub_url>/json) клиент отправляет идентификатор устройства и сведения об ОС в заголовках x-hwid, x-device-os, x-ver-os; x-device-model — если модель удалось определить. Это нужно для учёта устройств в панели (HWID device limit). Отключить отправку HWID в настройках нельзя.

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

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

• Автоподключение (on-demand): система сама поднимает и восстанавливает туннель при наличии сети. Строгий kill-switch не используется.
• Выбор языка интерфейса (системный / русский / английский) и автообновление подписок раз в сутки — в Настройках.
• macOS: виджет в строке меню — подключение/отключение, статус, открыть окно и настройки.
• Статистика трафика сессии и пинг серверов через прокси.
• Импорт и экспорт по QR-коду, копирование и шаринг ссылок.
• Локальное редактирование конфигураций (если не скрыто провайдером).
• Фрагментация TLS ClientHello для CDN (xHTTP): глобальный тумблер и query fragment в vless:// (1 или tlshello,100-200,10-20).
• Журнал туннеля и логи Xray с экспортом для диагностики.

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

• Возьмите ссылку подписки из панели и проверьте её в другом клиенте (например Happ) — wrab-* поля не должны ломать разбор.
• Откройте подписку в Wrabbit без wrab-mode — список серверов; строка «Авто» при ≥2 серверах в группе.
• Добавьте wrab-mode: auto-only — список серверов и пинги скрыты; одна строка с именем провайдера (Profile-Title) и подписью про автоподбор (не слово «Авто»).
• Роли: авто предпочитает direct, при недоступности берёт wl; hedge early-exit — только на живом direct. Маркер ~ — ручной выбор и UI-пинг, не авто-отбор.
• Сравните пинг «via Proxy» в Wrabbit и Happ — порядок величины должен совпадать (https://cp.cloudflare.com/generate_204, HTTP 2xx).
• Лицензия: без wrab-license брендинг/скрытие/роутинг выключены (это ожидаемо). С валидным токеном на ваш домен — включаются. Если домен в токене не совпадает с host подписки или токен истёк — фичи останутся выключенными.

Smoke-тесты для провайдеров (xray-json)

• <sub_url>/json отдаёт записи: после импорта серверы появляются, connect поднимает туннель из нативного JSON (routing/DNS/balancer панели).
• Мульти-outbound с decoy: задайте fallbackTag на рабочий путь — UI-пинг зелёный на живом WL-пути, а не на decoy REALITY.
• Decoy помечен в tag или другим транспортом, чем рабочий путь — пинг и connect не расходятся.
• Запись с dialerProxy / fragment: пинг «via Proxy» и connect оба проходят (не только connect).
• Trojan или Shadowsocks в xray-json (не только vless://): импорт и connect успешны; зону для них задавайте маркером в названии (не wrab-zone).
• Пара direct + wl: авто стартует на direct и умеет уйти на wl; нода с ~ в авто не попадает.