Skip to content

Client Quick Start

Connect to your r-vpn server in a few minutes.

Prerequisites

  • A running r-vpn server (see Server Quick Start)
  • The prekey-bundle.json file from your server operator

1. Download and Install

The easiest way is the universal installer:

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:

Platform Binary
macOS Universal rvpn-macos-universal
Linux x86_64 rvpn-x86_64-linux-gnu
Linux ARM64 rvpn-aarch64-linux-gnu
Linux ARMv7 rvpn-armv7-linux
FreeBSD x86_64 rvpn-x86_64-freebsd 
# macOS
curl -LO https://assets.rvpn.org/1.0.2/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.

# Linux

# Linux
curl -LO https://assets.rvpn.org/1.0.2/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.0.2/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

Each client has its own identity key (similar to a Signal keypair):

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

3. Create a Configuration File

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

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

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: 

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

(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. On macOS this appears as utunN; on Linux it defaults to rvpn0 (or your custom interface_name if specified). Your client IP address and gateway are assigned dynamically by the server.

Connect with the same command: 

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

Next Steps