Client Configuration Reference¶

Complete reference for all fields in client.toml.

Top-level Fields¶

Field	Type	Default	Description
`server_address`	string	`"wss://localhost:443/api/v1/ws"`	Full WebSocket URL of the server. Must include scheme (`wss://`), hostname, port, and path.
`sni_hostname`	string	(from URL)	Override the TLS SNI hostname sent during the handshake. Useful when connecting by IP address or CDN.
`identity_key_file`	path	`"identity.key"`	Path to your client identity key. Generated with `rvpn keygen`.
`prekey_bundle`	path	(none)	Path to the server's `prekey-bundle.json`. Required for first-time setup.
`server_public_key`	string	(none)	Hex-encoded server public key. Alternative to `prekey_bundle` when you only have the raw key.
`tls_fingerprint`	string	`"chrome"`	TLS ClientHello fingerprint to use. Options: `"chrome"`, `"firefox"`, `"safari"`, `"ios"`, `"android"`, `"edge"`, `"none"`. Use `"chrome"` for best DPI resistance.
`data_dir`	path	(platform default)	Directory for runtime data (known hosts, stats). Defaults to `~/.local/share/rvpn/` on Linux, `~/Library/Application Support/rvpn/` on macOS.

`[socks5]`¶

SOCKS5 proxy settings. These only apply when running in SOCKS5 mode (the default).

Field	Type	Default	Description
`listen_address`	string	`"127.0.0.1:1080"`	Address and port to accept SOCKS5 connections on. Use `"0.0.0.0:1080"` to share the proxy with other devices on your network.
`udp_associate`	bool	`true`	Enable SOCKS5 UDP ASSOCIATE command (for UDP-based apps).
`auth_enabled`	bool	`false`	Require username/password authentication for SOCKS5 clients.
`auth_username`	string	(none)	Username when `auth_enabled = true`.
`auth_password`	string	(none)	Password when `auth_enabled = true`.
`multiplex`	bool	`false`	Use a single multiplexed WebSocket for all connections. When enabled, uses 0-RTT flow creation for lower latency. Default `false` — one WebSocket per connection creates a traffic pattern that blends in with normal browsing. See Connection Modes.
`mux_path`	string	(auto)	Override the mux WebSocket endpoint path. Only used when `multiplex = true`. Defaults to `{server_path}/mux`.

[socks5]
listen_address = "127.0.0.1:1080"
auth_enabled   = true
auth_username  = "alice"
auth_password  = "hunter2"

`[http_proxy]`¶

HTTP/HTTPS proxy that runs alongside the SOCKS5 proxy. Disabled by default. Enables use of HTTP_PROXY/HTTPS_PROXY environment variables for system-wide or per-tool VPN routing. Both proxies share the same connection pool — running both simultaneously adds zero overhead.

Handles two request types:

HTTP CONNECT — used for HTTPS. The client sends CONNECT host:443 HTTP/1.1, the proxy establishes an encrypted tunnel to the destination.
Plain HTTP forwarding — used for unencrypted HTTP. The proxy connects to the host and forwards the request.

Both paths are split-tunnel-aware and use the same multiplexed WebSocket tunnel as SOCKS5.

Field	Type	Default	Description
`enabled`	bool	`false`	Start the HTTP proxy alongside the SOCKS5 proxy.
`listen_address`	string	`"127.0.0.1:8118"`	Address and port to accept HTTP proxy connections on.
`auth_enabled`	bool	`false`	Require Basic authentication for HTTP proxy clients.
`auth_username`	string	(none)	Username when `auth_enabled = true`.
`auth_password`	string	(none)	Password when `auth_enabled = true`.
`multiplex`	bool	`false`	Use a single multiplexed WebSocket. Default `false` is recommended — see Connection Modes.
`mux_path`	string	(auto)	Override the mux WebSocket endpoint path. Only used when `multiplex = true`. Defaults to `{server_path}/mux`.

[http_proxy]
enabled        = true
listen_address = "127.0.0.1:8118"

With authentication:

[http_proxy]
enabled        = true
listen_address = "127.0.0.1:8118"
auth_enabled   = true
auth_username  = "user"
auth_password  = "changeme"

See HTTP proxy setup for usage with environment variables and per-app configuration.

`[dns_proxy]`¶

Routes DNS queries through the encrypted tunnel to prevent DNS leaks in SOCKS5 mode. Disabled by default.

When enabled, the client listens for UDP DNS queries on listen_address and forwards them to the server's /dns WebSocket endpoint using the same X3DH + Double Ratchet encryption as regular traffic. Split tunnel rules are respected: bypass domains are resolved locally and blocked ad/tracker domains return NXDOMAIN immediately.

Field	Type	Default	Description
`enabled`	bool	`false`	Start the local DNS proxy alongside the SOCKS5 proxy.
`listen_address`	string	`"127.0.0.1:5353"`	UDP address and port for the DNS proxy. Use port `53` for system-wide compatibility (requires root or `CAP_NET_BIND_SERVICE`).
`nameservers`	list	`["223.5.5.5:53", "1.1.1.1:53", "8.8.8.8:53"]`	Public DNS servers used for bypass domains. Queries are sent directly via UDP to avoid looping back to the DNS proxy itself. CN users should put a local DNS first (e.g. `119.29.29.29:53`).

[dns_proxy]
enabled        = true
listen_address = "127.0.0.1:53"
nameservers    = ["223.5.5.5:53", "1.1.1.1:53", "8.8.8.8:53"]

See DNS proxy setup for instructions on pointing your system DNS at this address.

`[tun]`¶

TUN interface settings. Enable TUN mode by setting enabled = true. The client IP address, gateway IP, and DNS servers are assigned dynamically by the server via the VirtualIp message — do not set them manually.

Field	Type	Default	Description
`enabled`	bool	`false`	Enable full tunnel (TUN) mode. All IP traffic is routed through the VPN.
`interface_name`	string	(auto)	TUN interface name. On macOS the OS assigns a name like `utunN`. On Linux defaults to `rvpn0`. Optional — omit to use the OS-assigned name.
`routes`	list	`["0.0.0.0/0"]`	Routes to send through the tunnel. Default routes all traffic. Specify individual CIDRs for split-routing.
`mtu`	integer	`1420`	MTU of the TUN interface. Lower values reduce fragmentation on high-latency links.

[tun]
enabled = true
# interface_name = "rvpn0"  # optional, defaults to OS-assigned name
mtu     = 1420
routes  = ["0.0.0.0/0"]

`[split_tunnel]`¶

Controls which traffic bypasses the VPN and which is forced through it.

Field	Type	Default	Description
`enabled`	bool	`false`	Enable split tunneling. Must be `true` for any other split tunnel settings to take effect.
`builtin_bypass_countries`	list	`["CN"]`	Country codes whose IP ranges are automatically bypassed. Uses APNIC data. Supported: `"CN"`, `"HK"`, `"TW"`, `"RU"`, and others. Set to `[]` to disable.
`bypass_networks_file`	path	(none)	Path to a file of CIDR networks (one per line) that connect directly, bypassing the VPN.
`bypass_domains_file`	path	(none)	Path to a file of domain names (one per line) that connect directly.
`tunnel_networks_file`	path	(none)	Path to a file of CIDR networks that are forced through the VPN (overrides bypass rules).
`tunnel_domains_file`	path	(none)	Path to a file of domain names forced through the VPN.
`bypass_networks`	list	`[]`	Inline list of CIDR networks to bypass. Same as `bypass_networks_file` but defined directly in the config.
`auto_reload_interval`	integer	`86400`	How often (in seconds) to reload the bypass/tunnel files. Set to `0` to disable auto-reload.
`block_ads`	bool	`false`	Block known ad and tracking domains at the DNS level. No bytes sent to blocked domains.
`ad_block_file`	path	(none)	Path to a custom ad block list (one domain per line). Used in addition to the built-in list when `block_ads = true`.

[split_tunnel]
enabled                  = true
builtin_bypass_countries = ["CN"]
block_ads                = true
bypass_networks_file     = "~/.config/rvpn/bypass-networks.txt"

`[network]`¶

Client-side network behavior.

Field	Type	Default	Description
`ipv6_enabled`	bool	`true`	Enable IPv6 connections through the proxy.
`prefer_ipv4`	bool	`true`	When both IPv4 and IPv6 are available, prefer IPv4. Reduces latency on most networks.
`dns_cache_enabled`	bool	`true`	Cache DNS responses to reduce repeated lookups.
`dns_cache_ttl`	integer	`300`	How long (in seconds) to cache DNS entries.
`dns_cache_size`	integer	`1000`	Maximum number of entries in the DNS cache.
`dns_servers`	list	`[]`	Custom upstream DNS nameservers for resolving bypass domains (direct connections). Queries are sent directly via UDP to these servers, bypassing the system resolver entirely. Leave empty to use the system default. Useful when the system resolver is unreliable or you want to use a specific DNS provider for China traffic.

[network]
prefer_ipv4       = true
dns_cache_enabled = true
dns_cache_ttl     = 300
dns_servers       = ["223.5.5.5", "223.6.6.6"]  # Alibaba DNS for CN bypass domains

`[server_identity]`¶

Protects against server impersonation by verifying the server's X3DH key fingerprint.

Field	Type	Default	Description
`fingerprint`	string	(none)	Expected hex fingerprint of the server's Ed25519 identity key. If set, the client rejects connections where the server's key doesn't match.
`trust_on_first_use`	bool	`true`	Accept any server identity on the first connection and pin it for future verification (SSH-style TOFU).
`known_hosts_file`	path	`"known_hosts.json"`	Where to store pinned server identities.
`strict`	bool	`true`	If `true`, abort the connection on fingerprint mismatch. If `false`, only log a warning.

[server_identity]
trust_on_first_use = true
strict             = true

`[performance]`¶

Tuning for high-throughput or resource-constrained environments.

Field	Type	Default	Description
`worker_threads`	integer	`4`	Number of async worker threads. Increase on high-core servers.
`recv_buffer_size`	integer	`262144`	TCP receive buffer size in bytes (256 KB).
`send_buffer_size`	integer	`262144`	TCP send buffer size in bytes (256 KB).
`crypto_worker_count`	integer	`4`	Threads dedicated to encryption/decryption. Higher values improve throughput under heavy concurrent load.

[performance]
worker_threads     = 4
crypto_worker_count = 4

Full Example¶

server_address    = "wss://your.server.com/api/v1/ws"
identity_key_file = "~/.config/rvpn/identity.key"
prekey_bundle     = "~/.config/rvpn/prekey-bundle.json"
tls_fingerprint   = "chrome"

[socks5]
listen_address = "127.0.0.1:1080"

[http_proxy]
enabled        = true
listen_address = "127.0.0.1:8118"

[tun]
enabled = true
mtu     = 1420
routes  = ["0.0.0.0/0"]

[dns_proxy]
enabled        = true
listen_address = "127.0.0.1:53"
nameservers    = ["223.5.5.5:53", "1.1.1.1:53", "8.8.8.8:53"]

[split_tunnel]
enabled                  = true
builtin_bypass_countries = ["CN"]
block_ads                = true

[network]
prefer_ipv4       = true
dns_cache_enabled = true

[server_identity]
trust_on_first_use = true
strict             = true

Client Configuration Reference¶

Top-level Fields¶

[socks5]¶

[http_proxy]¶

[dns_proxy]¶

[tun]¶

[split_tunnel]¶

[network]¶

[server_identity]¶

[performance]¶