Skip to content

macOS App

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

Requirements

  • macOS 13.0 or later
  • A deployed r-vpn server
  • Server address, identity key, and prekey bundle

Setup

1. Install the App

Install r-vpn from the Mac App Store.

2. Add a Profile

Open the app from the menu bar icon, then go to Settings (or press Cmd+,).

Click + to add a new profile. Fill in:

  • Server Address: wss://your-server.com/api/v1/ws
  • Identity Key: Click Generate to create a new key pair, or Import to load an existing key file.
  • Prekey Bundle: Click Import Prekey Bundle and select the JSON file provided by your server administrator.

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

Split Tunnel

Split tunneling is enabled by default. It routes only international traffic through the VPN while letting domestic traffic (e.g. Chinese websites) go direct.

In the profile editor, configure:

  • Bypass Country: The country whose traffic should bypass the VPN (default: CN)
  • Bypass Domains: Additional domains to exclude from the tunnel
  • Tunnel Domains: Specific domains to force through the tunnel
  • Block Ads: Enable built-in ad domain blocking

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

Troubleshooting

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

  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

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 R-VPN entry.
  3. Re-open the R-VPN 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"

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 R-VPN entry and delete it.
  3. Re-open the R-VPN app. It will create a new profile on the next connection attempt.

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

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

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

For system-level logs:

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

Next Steps