Skip to content
rVPN rVPN

macOS App

The rVPN macOS app creates a full-tunnel VPN connection using a Network Extension. All traffic is routed through an encrypted tunnel.

Requirements

Section titled “Requirements”
  • macOS 13.0 or later
  • A deployed rVPN server
  • Server address, identity key, and prekey bundle

Setup

Section titled “Setup”

1. Install the App

Section titled “1. Install the App”

Install rVPN from the Mac App Store.

2. Add a Profile

Section titled “2. Add a Profile”

Open the app from the menu bar icon. Click Settings… (or press ⌘,). The Settings window has two segmented tabs — Profiles and Settings. Stay on Profiles.

Click the + button in the bottom toolbar (or click the up-arrow-into-doc icon next to it to import a .rvpn file exported from another device). The Profile editor opens in the window.

Fill in the fields you care about; the essentials are:

  • Name — anything you like (e.g. “Home HK”)
  • Colour — a swatch to identify the profile in lists and the menu bar
  • Default Profile — click the star row to make this the default (auto-connects on launch)
  • Server Address — wss://your-server.com/api/v1/ws/tun
  • Trust on First Use — leave on for standard TOFU pinning, or paste an expected Server Fingerprint below for stricter verification
  • Identity Key — click Generate to create a new X3DH identity for this profile, or Import… to load an existing key file
  • Prekey Bundle — click Import Prekey Bundle and select the JSON file provided by your server administrator
  • DNS Servers — comma-separated resolvers used when DNS falls back locally (default 1.1.1.1, 8.8.8.8)
  • Bypass Networks — extra CIDR ranges to send direct
  • MTU — TUN interface MTU (default 1420)
  • Split Tunnel — off routes everything through the VPN; on exposes the section below
  • Bypass Country — pick one built-in country (CN, HK, SG, JP, KR, and others) whose CIDR ranges bypass the tunnel
  • Bypass Domains — extra domains to send direct
  • Tunnel Domains — domains to force through the tunnel even when Split Tunnel is on

Click Save. The Identity Key and Prekey Bundle rows show a green checkmark once they’re present.

3. Connect

Section titled “3. Connect”

Click Connect in the menu bar dropdown. macOS will prompt you to allow the VPN configuration the first time. Approve it to proceed.

The app will:

  1. Connect to your server via TLS WebSocket
  2. Establish forward-secret encryption (X3DH + Double Ratchet)
  3. Receive a tunnel IP address from the server
  4. Route all traffic through the VPN

Once connected, the menu bar dropdown shows live IP, Uptime, and Sent/Recv counters — click the menu bar icon any time to check.

Split Tunnel

Section titled “Split Tunnel”

Split tunnel lives in the profile editor’s Traffic section. It routes only international traffic through the VPN and lets domestic traffic (e.g. Chinese sites) go direct. See the field list above for each setting.

Ad blocking is on for every profile and cannot be turned off from the UI (this matches the mobile apps).

Profiles

Section titled “Profiles”

The app supports up to 10 profiles. Switch between profiles from the menu bar dropdown or the Profiles settings tab.

Each profile stores its own:

  • Server address
  • Identity key
  • Prekey bundle
  • Split tunnel settings

Share a profile

Section titled “Share a profile”

To hand a profile off to another device — your iPhone, another Mac, a colleague — export it as a .rvpn file and share it however you like (AirDrop, email, Files.app).

Open Settings › Profiles, swipe or right-click on the profile you want to share, and pick Export. A dialog asks whether to include the identity key:

  • Export 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.
  • Include 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.

macOS then opens a save panel for the .rvpn file — from there you can drop it into AirDrop, attach it in Mail, or drag it into Messages.

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.

Server identity (TOFU)

Section titled “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 shows a Server identity changed alert 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.

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

Troubleshooting

Section titled “Troubleshooting”

App shows “Connected” but no traffic passes

Section titled “App shows “Connected” but no traffic passes”
  1. Check that your server is running and accessible on port 443.
  2. Verify the server address in your profile is correct (must start with wss://).
  3. Check the server logs for connection errors.

”Failed to start VPN” or connection fails immediately

Section titled “”Failed to start VPN” or connection fails immediately”
  1. Ensure both the identity key and prekey bundle are present in the profile editor (green checkmarks).
  2. Verify the server address does not have trailing whitespace.
  3. Regenerate your identity key and re-import the prekey bundle if the issue persists.

VPN stops working after an app update

Section titled “VPN stops working after an app update”

macOS persists VPN profiles in System Settings independently of the app. After an update, the stored profile may reference a stale tunnel extension.

Fix:

  1. Open System Settings > VPN (or System Settings > General > VPN & Filter on newer macOS).
  2. Delete the rVPN entry.
  3. Re-open the rVPN app and reconnect. The app will create a fresh profile.

This is resolved in version 1.2.4 and later, which automatically detects and replaces stale profiles.

VPN profile appears in System Settings but app shows “Disconnected”

Section titled “VPN profile appears in System Settings but app shows “Disconnected””

The VPN profile was likely created by a previous version or a different build. Remove it:

  1. Open System Settings > VPN.
  2. Click the info button (i) next to the rVPN entry and delete it.
  3. Re-open the rVPN app. It will create a new profile on the next connection attempt.

Tunnel connects but DNS does not resolve

Section titled “Tunnel connects but DNS does not resolve”

The app runs a local DNS proxy for split-tunnel DNS resolution. If DNS fails:

  1. Check that the server address is reachable.
  2. Try disabling split tunnel in the profile editor to use full-tunnel mode.
  3. Check the server logs for DNS proxy errors.

How to collect diagnostic logs

Section titled “How to collect diagnostic logs”

Rust-level logs are written to a file in the App Group container:

Terminal window
cat ~/Library/Group\ Containers/group.org.rvpn.client/rvpn_tunnel_rust.log

For system-level logs:

Terminal window
log show --predicate 'subsystem == "org.rvpn.tunnel"' --last 5m --level debug

Next Steps

Section titled “Next Steps”