Skip to content
rVPN rVPN

Client Quick Start

Connect to your rVPN server in a few minutes.

Prerequisites

Section titled “Prerequisites”
  • A running rVPN server (see Server Quick Start)
  • The prekey-bundle.json file from your server operator

1. Download and Install

Section titled “1. Download and Install”

The easiest way is the universal installer:

Terminal window
curl -fsSL https://assets.rvpn.org/install.sh | sudo bash -s -- --setup --client

It will auto-detect your platform, download the correct binary, verify the checksum, and walk you through configuration.

Or manually:

PlatformBinary
macOS Universalrvpn-macos-universal
Linux x86_64rvpn-x86_64-linux-gnu
Linux ARM64rvpn-aarch64-linux-gnu
Linux ARMv7rvpn-armv7-linux
FreeBSD x86_64rvpn-x86_64-freebsd

macOS App Store (recommended): Download from the App Store

Or install the command-line tool manually:

Terminal window
curl -LO https://assets.rvpn.org/1.3.1/rvpn-macos-universal
chmod +x rvpn-macos-universal && sudo mv rvpn-macos-universal /usr/local/bin/rvpn
xattr -d com.apple.quarantine /usr/local/bin/rvpn

Security note: Official macOS binaries are signed by PDG Global Limited. If you download a binary from another source that is not signed by us, do not use it.

Terminal window
# Linux
curl -LO https://assets.rvpn.org/1.3.1/rvpn-x86_64-linux-gnu
chmod +x rvpn-x86_64-linux-gnu && sudo mv rvpn-x86_64-linux-gnu /usr/local/bin/rvpn


# FreeBSD
fetch https://assets.rvpn.org/1.3.1/rvpn-x86_64-freebsd
chmod +x rvpn-x86_64-freebsd && sudo mv rvpn-x86_64-freebsd /usr/local/bin/rvpn

2. Generate Your Identity Key

Section titled “2. Generate Your Identity Key”

Each client has its own identity key:

Terminal window
mkdir -p /etc/rvpn
rvpn keygen -o /etc/rvpn/identity.key

3. Create a Configuration File

Section titled “3. Create a Configuration File”
Terminal window
nano /etc/rvpn/client.toml
server_address    = "wss://your-server.com/api/v1/ws"
identity_key_file = "/etc/rvpn/identity.key"
prekey_bundle     = "/etc/rvpn/prekey-bundle.json"


[socks5]
listen_address = "127.0.0.1:1080"

Copy prekey-bundle.json from your server operator to /etc/rvpn/prekey-bundle.json.

4. Connect

Section titled “4. Connect”
Terminal window
rvpn -c /etc/rvpn/client.toml

You should see:

INFO  Connecting to wss://your-server.com/api/v1/ws
INFO  SOCKS5 proxy listening on 127.0.0.1:1080

5. Configure Your Apps

Section titled “5. Configure Your Apps”

Set your system or browser proxy to SOCKS5 127.0.0.1:1080.

macOS System Proxy: System Settings → Network → your connection → Proxies → SOCKS Proxy → 127.0.0.1:1080

Chrome / Brave (via extension): Install SwitchyOmega and add a SOCKS5 proxy at 127.0.0.1:1080.

Firefox: Settings → General → Network Settings → Manual proxy configuration → SOCKS Host: 127.0.0.1, Port: 1080, SOCKS v5.

curl:

Terminal window
curl --socks5 127.0.0.1:1080 https://example.com

(Optional) Full Tunnel (TUN) Mode

Section titled “(Optional) Full Tunnel (TUN) Mode”

Instead of a SOCKS5 proxy, you can enable full tunnel mode to route all IP traffic through the VPN. TUN mode requires root or administrator privileges.

Add [tun] to your client.toml to enable it:

[tun]
enabled = true

The interface name is assigned automatically by the operating system — typically utun0 on macOS and tun0 on Linux/FreeBSD. Pass a custom interface_name in the [tun] section if you want a specific name. Your client IP address and gateway are assigned dynamically by the server.

Connect with the same command:

Terminal window
sudo rvpn -c /etc/rvpn/client.toml

Next Steps

Section titled “Next Steps”