Wrabbit Documentation

What Wrabbit is

Wrabbit is a client, not a VPN service. It has no servers of its own and sells no access. You add your own vless://, trojan://, ss:// links or a subscription URL — keys and configs stay only on your device.

• Core — Xray-core; protocols VLESS, Trojan, Shadowsocks.
• Flexible IP-list routing and automatic server selection.
• Compatible with panel subscriptions (Remnawave and compatible) — no account, no sign-up.

Quick start

• Install Wrabbit on your iPhone (iOS 16 or later).
• Tap “+” and add a configuration: paste a link from the clipboard, scan a QR code, or paste a subscription URL. The format is detected automatically.
• Pick a server or the “Auto” mode and tap “Connect”. On the first connection iOS will ask you to allow the VPN profile.

If a subscription stops serving servers (expired or out of traffic), the card shows a banner and a “Renew” button — access info comes from the subscription response, see “Subscriptions for providers”.

Importing configs and subscriptions

Supported formats

How to add

• Paste from the clipboard or into the import text field.
• Scan a QR code with the camera.
• Manual config editor (VLESS / Trojan / Shadowsocks).

The client tells them apart: a single http(s):// link with no line breaks → subscription; a single vless:// → standalone server; multi-line text or trojan:///ss:// → bulk parsing.

Subscription updates

• The request uses the Wrabbit User-Agent and bypasses cache (Cache-Control: no-cache), 20-second timeout.
• A successful response fully replaces the subscription's server list; a manual selection is preserved if the same server remains.
• Network errors and 4xx/5xx codes leave the old list intact — an “Update failed” toast is shown.
• Auto-update runs once a day with a global toggle in settings. A subscription update-interval header is not honored at the moment.

Protocols and transports

VLESS+REALITY requires pbk and sni (optionally sid, flow, fp, servicename). xHTTP/CDN needs path and sni/host. Flow: none or xtls-rprx-vision.

Routing

By default all traffic goes through the tunnel. Local/private networks are excluded automatically. Additionally, selected addresses can be sent directly, bypassing the tunnel (IP split-tunnel).

Routing lists

• Format — IPv4 CIDR (a single IP is treated as /32). Separators: newline, comma, space or ;.
• Lists are added by text or by link (plain text file) and refreshed from that link.
• For the Russian locale a ready-made RU-zone preset is seeded once; routing is enabled with a toggle.

Auto mode and server selection

In “Auto” mode the client pings the group's servers through a proxy before connecting (it spins up an ephemeral Xray and checks reachability), then picks the fastest live server.

Servers are split into direct (fast direct, e.g. REALITY) and whitelist (reachable under blocking, usually CDN fronts) zones. Priority goes to the fastest live direct; if there are none — whitelist. On iPhone, with several candidates, the tunnel can restart and switch between servers on connectivity drops.

Subscriptions for providers

Wrabbit reads subscription metadata via two channels: HTTP response headers (the primary source) and, as a fallback, a line in the subscription body prefixed with # (e.g. #wrab-mode: auto-only). The header always wins over the body line.

wrab-zone — server role (inside the link)

The per-server role is set with a query parameter in vless://: wrab-zone=direct (fast direct) or wrab-zone=wl (CDN/whitelist). Without a label the role is derived from the transport: CDN/WebSocket → whitelist, REALITY → 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=allow.example.com&path=/xh&host=allow.example.com&wrab-zone=wl#NL-1 CDN

Expired or disabled subscription

When a subscription is no longer active, the panel returns HTTP 200 with metadata but no servers. Wrabbit treats this as a “no access right now” signal (not an error): servers are removed, a banner and a renew button appear (pointing to Support-Url), and an active tunnel on the vanished server is disconnected. The state clears on the next update once servers return.

Remnawave integration

Everything is configured with the panel's native tools, no forks. Labels are delivered three ways:

• Globally per client — Subscription Response Rules: a rule with user-agent CONTAINS wrabbit and a header, e.g. wrab-mode: auto-only. Other clients are unaffected.
• Per-user / per-group — External Squads: the responseHeaders field, e.g. { "wrab-mode": "auto-only" }, assigned to selected users.
• Server role wrab-zone — via host templates or an XRAY_JSON template; for the current fleet the transport heuristic is usually enough.

Branding in Remnawave: Announce ← happAnnounce, Support-Url ← supportLink (both in subscription-settings), wrab-logo ← customResponseHeaders or an External Squad's responseHeaders.

Privacy and device

Wrabbit keeps no traffic logs and shares no configurations with third parties. When requesting a subscription it sends, by default, a device identifier (HWID) and the model in the x-hwid, x-device-os, x-ver-os, x-device-model headers — needed for correct device accounting in the panel. HWID sending can be disabled in settings.

• Platform: iPhone, iOS 16 and later (Packet Tunnel / Network Extension).
• No analytics or trackers; only anonymized crash reports are collected.
• Localization: Russian and English (plus the system language).

Extra features

• Kill-switch on disconnect and on-demand auto-connect.
• Session traffic stats and server ping via proxy.
• QR import and export, copy and share links.
• Local config editing (unless hidden by the provider).
• CDN fragmentation (anti-DPI) — a global toggle and the fragment parameter in the link.
• Tunnel journal and Xray logs with export for diagnostics.

Compatibility checklist

• Take the subscription link from the panel and test it in another client (e.g. Happ) — wrab-* fields must not break parsing.
• Open the subscription in Wrabbit without wrab-mode — a normal server list and “Auto”.
• Add wrab-mode: auto-only — only the “Auto” row should remain, servers and pings hidden.
• Check wrab-zone labels: “Auto” picks primary=direct, alt=whitelist.
• Compare the “via Proxy” ping in Wrabbit and Happ — the order of magnitude should match.