iOS App

The rVPN iOS app creates a full-tunnel VPN connection to your server. All device traffic is routed through an encrypted tunnel.

Requirements

iOS 16.0 or later
A deployed rVPN server
Your server address, and either a .rvpn profile export from another device or a prekey bundle from your server administrator

Install

Install rVPN from the App Store.

Add your first profile

The app is organised around profiles — each profile bundles a server address, identity key, prekey bundle, and split-tunnel rules. You can have up to 10 profiles and switch between them from the Home screen.

Open the app. On the Home screen, tap the profile card (“No Profile Selected”) to open the profile switcher, or go to the Settings tab → Manage Profiles.

You have two options:

Import an existing profile

If someone has shared a .rvpn file with you (exported from another device or provided by your administrator), open the profile switcher from the Home card and tap the import icon at the bottom. Pick the file. The profile lands in your list with all keys pre-populated.

Create a profile from scratch

Tap Add New Profile. In the Profile editor, fill in:

Name — anything you like (e.g. “Home HK”)
Colour — a swatch to help you identify the profile at a glance
Server Address — wss://your-server.com/api/v1/ws/tun
Identity Key — tap Generate to create a new X3DH identity, or Import to load an existing key file
Prekey Bundle — tap Import Prekey Bundle and pick the JSON file your server administrator provided

The Identity Key and Prekey Bundle rows show a green checkmark once they’re present. Tap Save in the top right.

Connect

Back on the Home screen, tap the big Connect button. iOS will prompt you to allow the VPN configuration the first time — approve it to proceed. The app will:

Connect to your server over TLS 1.3 WebSocket
Establish forward-secret encryption (X3DH + Double Ratchet)
Receive a tunnel IP address from the server
Route all traffic through the VPN

Once connected the Home screen shows your assigned IP, session uptime, and running sent/received byte counts. Tap the button again to disconnect.

Switch profiles

On the Home screen, tap the active profile card to open the profile switcher. Tap another profile to make it active. If a tunnel is already up, the app will disconnect, switch, and reconnect using the new profile.

To hand a profile off to another device — your iPad, a friend’s phone, another Mac — export it as a .rvpn file and share it however you like (AirDrop, Messages, Files).

Open the profile switcher from the Home card, swipe left on the profile you want to share, and tap Export. iOS asks whether to include the identity key:

Without identity — safer. The recipient can inspect the profile and connect using their own key material (they need a prekey bundle from the same server administrator). Use this when sharing across users or into an untrusted place.
With identity — the recipient can connect as-is on another device. Only pick this if the other device is yours, or you fully trust the recipient. The exported file contains your private key.

iOS then shows the share sheet — AirDrop, Files, Messages, whatever fits. The file lands with a .rvpn extension.

The exported file also carries the server’s pinned identity (ik:1: fingerprint) once you’ve connected at least once. That means the recipient’s client refuses to connect if the server ever presents a different key, and no separate out-of-band verification is needed — the sender has vouched for the server by handing you the file. See Server Identity Pinning for the full model.

Split tunnel

Route only international traffic through the VPN while local traffic goes direct.

Open the Profile editor for the active profile (Settings → Manage Profiles → tap your profile). Under Traffic:

Split Tunnel — turn it on
Bypass Countries — comma-separated country codes whose CIDR ranges bypass the tunnel (defaults to CN)
Bypass Domains — extra domains to send direct
Tunnel Domains — domains to force through the tunnel even when Split Tunnel is on

Save. The next connection uses the new rules.

DNS

By default, DNS is resolved through the tunnel. To use custom upstream resolvers, edit the profile → Network → DNS Servers and enter a comma-separated list (e.g. 1.1.1.1, 8.8.8.8).

Server identity (TOFU)

Trust on First Use (on by default per profile) accepts and pins the server’s identity on the first successful connection. Pins are written in the canonical ik:1:<base32> form and live on the profile itself.

If the server ever presents a different key, the app opens a Server identity changed dialog with the pinned and received pins side-by-side and three options: Cancel, Delete Profile, or Trust New Identity. If the operator rotated the key using the signed rotation ceremony, the app updates the pin silently — no dialog.

For stricter verification, paste the pin (from the operator, in ik:1: form) into the profile’s Server Fingerprint field before the first connect.

If your profile is missing its identity key or prekey bundle when you tap Connect, the app now surfaces a clear warning (“The profile “X” needs an identity key and a prekey bundle. Edit the profile and Generate Identity / Import Prekey Bundle.”) before trying to start the tunnel — no more silent “Connecting…” cycles that go nowhere.

For the full model — pin format, rotation ceremony, threat model — see Server Identity Pinning.

Troubleshooting

”Failed to start VPN”

Verify server address is correct and starts with wss://
Verify the Identity Key row shows a green checkmark
Verify the Prekey Bundle row shows a green checkmark
Verify your server is reachable on port 443

”No IP assigned”

The server’s IP pool is exhausted. Contact your server administrator to widen the DHCP range in rvpn.toml.

Split tunnel not working

Verify Split Tunnel is on in the profile editor
Verify the Bypass Country code (e.g. CN, not China)
Toggle Airplane mode to refresh the routing table

Slow connection

Try different DNS servers
Check server load
Verify Split Tunnel isn’t sending too much traffic direct

For more troubleshooting help, see the Troubleshooting Guide.