v2RAGE for providers

How to give your users a subscription in v2RAGE with one tap, and which links and configurations the app accepts. This page describes v2RAGE 2.4.1 for iPhone, iPad and Mac from the App Store. Items marked Next update are already done and ship in the next version of the app.

Add-subscription link

The link opens v2RAGE and offers to add your subscription:

v2rage://import?url=<subscription URL, percent-encoded>

• url is the full subscription address, https:// or http://, percent-encoded as a whole (encodeURIComponent in JavaScript). An unencoded & from your own query splits the address, and the app receives only its beginning.
• The app shows the address and asks “Add this subscription?” Nothing is downloaded until the user taps Add.
• On success the user sees “Subscription added — N servers”. If the response holds no server the app can read, the user sees “No servers found in subscription”, and nothing is added.
• The list of subscriptions is stored on the device and synced through the user's iCloud when it is available.
• Opening the link for an address that is already added replaces the earlier copy instead of adding a second one. Letter case of the scheme and host, a #fragment and a trailing slash do not make the address different.
• Only subscription addresses are accepted. A single server key (vless://…, hy2://…) cannot be passed in url: put it into a subscription, or let the user paste it on the import screen.

Example

Subscription address:

https://panel.example.com/sub/abc?format=v2ray

Link:

v2rage://import?url=https%3A%2F%2Fpanel.example.com%2Fsub%2Fabc%3Fformat%3Dv2ray

Button on your page:

<a href="v2rage://import?url=https%3A%2F%2Fpanel.example.com%2Fsub%2Fabc%3Fformat%3Dv2ray">Add to v2RAGE</a>

Where to put the link

• Behind a button on an https:// page: your dashboard or a landing page. A tap in Safari opens the app.
• Messenger in-app browsers often do not open custom schemes, and a QR code with a v2rage:// link may not open from the camera. In messages and QR codes, point to your https page with the button rather than to the v2rage:// link itself.
• Next to the button, show the plain subscription address with a copy button. The user can always paste it in the app: Settings → Import Subscription.
• If v2RAGE is not installed, the link does nothing. Add the App Store link: apps.apple.com/app/v2rage/id6761075402.

Manual import

Settings → Import Subscription accepts:

• a subscription address (https://…);
• a single server link, see Supported configurations;
• an AmneziaWG configuration: an awg:// link or the text of a .conf file;
• any of the above from a QR code, with the Scan QR button.

Subscription URL

Request

The app downloads the subscription with a GET request and these headers:

The x-* headers follow the convention of Happ, Remnawave and 3x-ui 3.7+: a panel counts devices by x-hwid. If your panel counts devices, refuse requests without a valid x-hwid with the x-hwid-not-supported header, see Device limit.

Response

• Status 200, body in UTF-8. Any other status is shown to the user as an error.
• Body: one server link per line, or the same list encoded in standard Base64 as one line, without spaces or line breaks, with or without = padding. One subscription can mix protocols.
• Lines the app cannot read are skipped, the rest are added.
• Not supported as a subscription body: Clash / Mihomo YAML, sing-box JSON, Xray JSON. If your panel chooses the format by User-Agent, return the plain link list for v2RAGE/….
• A Base64 body is recognised only when it holds at least one vless://, vmess://, hysteria2:// / hy2://, hysteria://, tuic://, socks:// or socks5:// link. Serve a subscription made only of awg://, wireguard://, socks4://, socks4a:// or socks5h:// links as plain text. Next update awg:// is recognised in Base64 too.

Response headers

Send these header names in lowercase, as written above. A complete response:

HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8
profile-title: base64:TXkgVlBO
subscription-userinfo: upload=0; download=1073741824; total=107374182400; expire=1798761600

vless://11111111-2222-3333-4444-555555555555@nl1.example.com:443?type=tcp&security=reality&flow=xtls-rprx-vision&pbk=<public key>&sid=<short id>&sni=www.example.org&fp=chrome#NL%20Amsterdam

profile-update-interval is read but not used for scheduling. On iPhone, iPad and Mac the subscription is downloaded again when the user refreshes the server list or the subscriptions in settings. On Apple TV it is also refreshed when the server screen opens, at most once every 15 minutes.

Device limit

A panel that counts devices can refuse with these response headers. The status code does not matter: Remnawave, for example, answers 404.

Subscriptions a user adds are synced through their iCloud to their other Apple devices with v2RAGE. Each device downloads the subscription with its own x-hwid and counts as a separate device.

Supported configurations

Server links, inside a subscription or pasted one by one. Everything after # is the server name. Start the name with a flag emoji or a two-letter country code (🇳🇱 Amsterdam, NL Amsterdam) to set the server's country.

Link rules

• Set sni explicitly for TLS keys: Hysteria 2, Hysteria, TUIC, VMess with TLS.
• VLESS: write host:port?…, without / between the port and ?. Do not repeat parameters. Write sni, host and the other values without percent-encoding; only path may be encoded.

Not supported

• NaiveProxy (naive+https://).
• HTTP and HTTPS proxies.
• Clash / Mihomo YAML, sing-box JSON and Xray JSON.
• Shadowsocks and Trojan in version 2.4.1: such keys are rejected when pasted and skipped in a subscription. See below.

Next update

Already done and shipping in the next version of v2RAGE. Until it is released, these keys do not work in the App Store version.

For Shadowsocks and Trojan, a parameter repeated in one link makes the key rejected.