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.
• Platforms: iPhone / iPad (iOS 16 and later) and Mac (macOS 13 and later) — one app, the same configs and subscriptions.
• Flexible IP-list routing and automatic server selection.
• Compatible with panel subscriptions (Remnawave and compatible) — no account, no sign-up.

Quick start

• Install Wrabbit from the App Store: iPhone / iPad (iOS 16 or later) or Mac (macOS 13 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 or macOS will ask you to allow the VPN profile.

macOS

• The same client in the Mac App Store (Mac Catalyst): import, subscriptions, auto mode and routing work the same as on iPhone.
• A menu bar icon: quick connect/disconnect, status, open the window, settings and quit — without bringing the app to the foreground.
• QR codes are scanned with the Mac camera (on first use the system asks for permission; the prompt is localized to the app language).

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.

Domain routing from subscription (Happ standard)

A provider can deliver routing rules with the subscription via the routing header (the same format as Happ: happ://routing/onadd/<base64-json>). Wrabbit applies DirectSites/ProxySites/BlockSites (domains) and DirectIp/ProxyIp/BlockIp (CIDR). Domain rules work via connection sniffing. Manage it in Settings → Domain routing.

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 can be given a role: regular (direct) — fast direct servers, and special (wl) — reserve servers for auto mode. Priority goes to the fastest live regular server; if there are none, the client uses a special one. On iPhone and Mac, with several servers, the tunnel can restart and switch between them on connectivity drops.

For hosts with multiple edge entry points (a balancer configured in the panel) Wrabbit additionally fetches the same subscription in xray-json format (<url>/json) and uses the native balancer pool — parity with Happ. If /json is unavailable or the subscription is third-party, the client simply works with a single outbound. No extra setup is needed on the provider side.

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 server's auto-mode role can be set explicitly with a query parameter in vless://: wrab-zone=direct (regular) or wrab-zone=wl (special/reserve). The role is also recognized from a marker in the server name (e.g. WL). Without a marker the server is treated as regular (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

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.

Provider licensing (premium integration)

Wrabbit is a neutral free client: we take no payment from users and there are no paid features in the app. Some integration capabilities are premium and available to providers under a license (B2B, outside the app). This is the client's monetization: the provider pays for extended integration, the end user never does.

What is free and what needs a license

How it works

A license is a signed token bound to your subscription domain and an expiry. You put it in the wrab-license response header (or a #wrab-license: line in the body — for static files). The client verifies the signature offline with an embedded key (Ed25519) — it never contacts our servers for this. If the token is valid, not expired, and its domain matches your subscription host, the matching premium features turn on. No token or an invalid one — those features are simply off, and the rest of the subscription works as usual.

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:SGVsbG8h
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

Token format

Token: v1.<base64url(payload)>.<base64url(Ed25519 signature)>. The payload is compact JSON: dom (subscription domain), feat (feature array — brand/hide/routing), exp (Unix expiry), kid (key id). The signature covers the string v1.<base64url(payload)>. Only we issue tokens: a signature cannot be forged with just the public key embedded in the client.

How to get a license

There is no self-serve dashboard yet — we issue licenses manually. Contact us (see Support): send your subscription domain(s) and the feature set you need, and we will issue a token for an agreed term. Renewal and revocation are on our side.

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 — via a marker in the name (e.g. WL) or the wrab-zone parameter in the link itself.

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

Domain routing: the routing header comes from Subscription Settings → Happ Routing (happRouting). Build the profile at routing.happ.su and deliver it as a single line — the same profile is applied by both Happ and Wrabbit (Wrabbit: explicit domains/CIDR, no geo categories).

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.

• Platforms: iPhone / iPad (iOS 16 and later) and Mac (macOS 13 and later). The tunnel uses Packet Tunnel / Network Extension on both.
• On Mac — a menu bar widget for quick VPN control without opening the window.
• No analytics or trackers; only anonymized crash reports are collected.
• Localization: Russian and English (plus the system language). OS permission prompts (camera, VPN) follow the app's interface language.

Extra features

• Kill-switch on disconnect and on-demand auto-connect.
• macOS: menu bar widget — connect/disconnect, status, open the window and settings.
• Session traffic stats and server ping via proxy.
• QR import and export, copy and share links.
• Local config editing (unless hidden by the provider).
• TLS ClientHello fragmentation for CDN servers — a connection-compatibility option (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 server roles: “Auto” prefers a regular (direct) server and falls back to a special (wl) one when unavailable.
• Compare the “via Proxy” ping in Wrabbit and Happ — the order of magnitude should match.
• Licensing: without wrab-license, branding/hiding/routing are off (this is expected). With a valid token for your domain they turn on. If the token's domain does not match the subscription host, or the token is expired, the features stay off.