VPN Control

The VPN Control page lets you manage your WireGuard and OpenVPN VPN directly from the dashboard. Add peers, manage OpenVPN client tunnels, monitor active connections on a geographic map, configure app-scoped VPN routing, and generate NordVPN configurations — all without touching the command line.

Admin only

VPN Control requires admin privileges (admin.system.vpn permission). Navigate to System > VPN Control from the sidebar.

VPN Control is the admin cockpit — users have a separate self-service surface

This page is the administrator cockpit: provisioning peers, generating NordVPN configs, enabling app routing for any user, and running the OpenVPN/WireGuard gateways. A non-admin never sees it. When you grant a user the VPN (OpenVPN) or WireGuard app through their ACL group, that user gets a compact self-service panel on their own Applications page — they can download their own config, see their routed apps and exit location with live metrics, and toggle their own already-provisioned routes. They cannot provision a new route or touch anyone else’s. See the OpenVPN and WireGuard self-service sections.

A VPN backend is required

At least one VPN backend — WireGuard or OpenVPN — must be installed before the VPN Control page is functional. If neither is installed, the page displays a prompt with a link to Package Management. Administrators can install either backend from Package Management or the CLI — WireGuard with qb install wireguard, OpenVPN with qb install vpn -u username (the OpenVPN install modal sets the listen port, protocol, client subnet, and pushed DNS). When both are installed, a WireGuard | OpenVPN selector appears at the top of the page so you can switch between the two surfaces.

Key features

Geographic Visualization

View active VPN connections on an interactive map showing peer locations

Peer Management

Add, activate, deactivate, and remove WireGuard peers with configuration upload

App-Scoped Routing

Route specific applications through WireGuard or OpenVPN using network namespaces with kill switch support

Connection Monitoring

Real-time data transfer statistics and connection history for all peers

Server Keys

View WireGuard server public and private keys, listen port, and DNS configuration

NordVPN Generator

Generate WireGuard-compatible NordVPN configurations by selecting a country

OpenVPN Management

View OpenVPN server status and per-user profiles, and upload, activate, deactivate, or delete client tunnels

VPN overview

The top of the page features a hero section divided into two areas:

Active Connection Carousel — Displays your active VPN connections (both system VPN and app routing connections) in a rotating carousel. Each card shows the connection name, status, endpoint, and data transfer statistics. The carousel auto-rotates and pauses when you interact with it.
Geographic Map — An interactive map that highlights the geographic location of the currently selected connection. As the carousel rotates or you select a connection, the map updates to show where that peer is located.

Peer management

The peer table below the hero section lists all configured WireGuard peers. Each row shows the peer name, endpoint, status, and available actions.

Adding a peer

Upload a WireGuard configuration file to add a new peer:

Click Add Peer or the upload button
Select a .conf file containing the WireGuard peer configuration
The peer appears in the table in a deactivated state

Activating and deactivating peers

Activate — Bring a peer connection online. Only one system VPN connection can be active at a time — activating a new one deactivates the current one
Deactivate — Take a peer connection offline without removing it

Click the expand arrow on any peer row to view the full WireGuard configuration details.

Removing a peer

Click Delete on a peer row to permanently remove its configuration from the server.

OpenVPN

When OpenVPN (the vpn package) is installed, switch to the OpenVPN tab using the selector at the top of the page. The OpenVPN surface has three parts.

Server status and per-user profiles

A status card shows whether the OpenVPN server is installed and running, along with its subnet and port. A profile table lists the per-user .ovpn profiles the installer built for end users to download. You can view a profile’s contents from the dashboard — private keys and tls-crypt material are redacted on screen. The downloadable bundle itself is served from the nginx route created at install time; see the OpenVPN application docs.

Client tunnel management

Client tunnels are the OpenVPN analogue of WireGuard peer configs — a provider .ovpn the box itself dials out through, used to carry app-scoped routing. Upload a config from your VPN provider (Mullvad, PIA, NordVPN, and so on); the dashboard stores it in /etc/v4-dashboard/openvpn/ and drives the openvpn-client@<name>.service unit.

Action	What it does
Upload	Adds one or more `.ovpn` client configs. A server-style config is rejected with a clear message.
Activate	Starts the client tunnel (exclusive — stops any other active client tunnel first).
Deactivate	Stops the client tunnel. Any app routing using it is torn down first.
Delete	Deactivates then removes the config from both the system and the stash.

All four actions run as background jobs with a live console, mirroring the WireGuard peer workflow.

Server vs client tunnels

The OpenVPN server (built by qb install vpn) accepts inbound clients connecting into your box. A client tunnel uploaded here dials out through a remote provider so an app’s traffic egresses elsewhere. They are independent and never collide.

NordVPN config generator

The VPN Control page includes a built-in NordVPN configuration generator. Select a country from the dropdown, and the dashboard generates a WireGuard-compatible configuration file that you can use to connect through NordVPN’s network.

This is particularly useful for routing specific applications through a VPN for privacy or geo-restriction bypass.

NordVPN and full-tunnel routing

Configurations generated by the QuickBox NordVPN generator are built for full-tunnel egress, which is required for VPN app-routing to work correctly. This ensures all outbound traffic from the routed application goes through NordVPN — a prerequisite for Plex’s direct-connect remote access to work. Configs from older QuickBox installs that used partial-tunnel routing are automatically corrected the next time app-routing is applied for that application.

App-scoped VPN routing

One of the most powerful VPN features is the ability to route specific applications through the VPN while keeping everything else on the direct connection. This uses Linux network namespaces to isolate VPN traffic per application.

Choosing a tunnel backend

App-scoped routing can carry an app’s traffic over either WireGuard or OpenVPN. When you expand an app in the App-Scoped Routing card, a Tunnel Backend selector lets you pick which one to use — the OpenVPN option appears only once at least one OpenVPN client tunnel has been uploaded (see OpenVPN > Client tunnel management above). Pick the backend, then select a matching config: a WireGuard peer for the WireGuard backend, or an OpenVPN client tunnel for the OpenVPN backend.

Everything else — kill switch, automatic failback, health monitoring, the namespace model, inbound access paths — behaves identically regardless of backend. An already-enabled route shows its locked-in backend in the Current Routing panel and cannot be switched in place; disable and re-enable to change it.

Per-backend config rules

The “config already in use” guards are scoped per backend — a WireGuard peer and an OpenVPN client tunnel that happen to share a name never falsely conflict. Within a backend, each active routing slot still needs its own distinct config.

Two routing modes

WireGuard on QuickBox Pro operates in two distinct modes. Understanding the difference matters before configuring either one.

Peer activation (main VPN) — Toggling the Active switch on a peer in the peer table starts a wg-quick@<peer> tunnel that routes all server traffic through that peer. Every outbound connection from your server — the dashboard, SSH, running applications — exits through the VPN. This is a full-tunnel, server-wide configuration. Only one system VPN peer can be active at a time.

App-scoped routing — A separate feature that routes only one application’s traffic through a WireGuard tunnel using a private Linux network namespace. The rest of the server keeps its default route. Dispatcharr, Emby, Jellyfin, Plex, and qBittorrent are supported. Each routed app runs inside its own isolated namespace with a dedicated WireGuard interface, so there is complete traffic separation.

Both modes can run simultaneously — but each active routing slot requires its own WireGuard peer config.

One peer config per routing slot — no sharing

A WireGuard peer config holds exactly one session with the VPN provider: one keypair, one handshake, one tunnel. You cannot share a single .conf file across multiple slots. This applies in two ways:

If you have a main VPN peer active and also want to use app-scoped routing, you need a second .conf for the app routing slot. Reusing the active peer config will cause the app’s handshake to fail (Bad Gateway).
If you want to route multiple apps simultaneously — for example, both Emby and qBittorrent — each app needs its own distinct .conf file. Two apps cannot share one config; the second app’s namespace will fail to connect.

Upload one .conf per routing slot from your VPN provider. All configs can point to the same VPN provider or server — they just need independent files with their own keys.

How app-scoped routing works

Enable routing for an app — The selected application’s traffic is routed through the active VPN connection
Kill switch — When enabled, the app loses network access entirely if the VPN disconnects, preventing unprotected traffic
Live stats — Real-time routing statistics streamed via server-sent events show data transfer per routed app

The app runs server-side in a namespace — the exit location is the app's, not a device's

App-scoped routing runs the application on the server inside a private network namespace; that namespace’s egress exits through the VPN. No one installs a tunnel client on their own device for app routing. The exit location and egress IP shown for a routed app are where the app’s outbound traffic appears to originate (the VPN provider’s exit), not any user’s device.

Routing is restored automatically after a reboot

App-scoped routing survives a server reboot with no manual step. When the box comes back up, QuickBox Pro rebuilds every routing namespace and tunnel and restarts the routed services automatically.

Apps are held until their namespace exists, so routed services no longer race ahead of the tunnel and flap at boot.
Routed services start in parallel and non-blocking, so one slow app cannot stall recovery of the others.
A boot run that stalls self-heals. The reconcile step has a generous timeout (up to 10 minutes for a multi-namespace rebuild) and retries on failure, and a periodic safety-net timer re-checks routing shortly after boot and again on an interval — worst case the system converges within about 15 minutes.

You do not have to re-enable any routing profile after a reboot. If a routed app looks briefly disconnected right after boot, give the safety-net recovery a few minutes to converge before intervening.

Reaching an app-routed service

App-scoped routing tunnels the app’s outbound traffic through the VPN. Your inbound access paths stay the same.

Path	How it works
LAN (local network)	Reach the app at `http://<server-LAN-IP>:<port>` from any device on the same local network. Example: `http://192.168.1.10:8096` for Emby. The namespace is on the server — LAN-adjacent clients connect as normal.
Reverse proxy (recommended)	An internal veth link bridges the namespace to the server’s reverse proxy. Access the app at `https://<your-server-or-domain>/<username>/<app>/` on port 443, whether you are on LAN or remote.
Remote / WAN	Use the reverse proxy URL or your own domain. The app’s raw port is not automatically exposed on your server’s public IP when it runs inside a namespace — remote clients should connect through the proxy or a port-forward you explicitly configure.

App-scoped routing has no effect on how you reach the app — only on where the app’s own connections exit.

VPN carries outbound traffic only

The app cannot make outbound calls except through the tunnel, so there is no privacy leak. Inbound traffic from your clients arrives through the reverse proxy veth bridge, not through the VPN, so your access is unaffected.

Plex-specific inbound bypass

Plex has additional handling beyond the general model above. QuickBox wires Plex’s inbound and outbound paths separately:

Outbound (library scans, plex.tv API, account registration) — routed through the VPN tunnel as usual
Inbound (remote clients connecting to your server on port 32400) — delivered directly via your server’s real public IP, bypassing the VPN for the return path

This means Plex can register correctly with plex.tv using a reachable address, and clients connect at full bandwidth without going through Plex Relay. The inbound bypass is automatic when you enable VPN routing for Plex — no additional configuration is needed.

For downloaders like qBittorrent, inbound connections come through the VPN peer port (set via the Peer Listen Port field), so those connections travel through the tunnel end-to-end rather than using the bypass.

Supported applications

Dispatcharr

Emby

Jellyfin

Plex

qBittorrent

Application	Service Type	Service Unit	Notes
Dispatcharr	Per-user (4-service stack)	`dispatcharr-gunicorn@{username}` plus daphne, celery-worker, celery-beat	All four application services routed together in one namespace; PostgreSQL and Redis stay on the host
Emby	Per-user (template)	`emby-server@{username}`	One routing profile per user instance
Jellyfin	Per-user (template)	`jellyfin@{username}`	One routing profile per user instance
Plex	System-wide	`plexmediaserver`	Inbound bypass enabled — full remote access at direct-connect speeds
qBittorrent	Per-user (template)	`qbittorrent@{username}`	Peer listen port required — must match qBittorrent's setting

Installed applications with running services appear in the routing card. Plex also appears even when not yet installed, because VPN routing can be staged before install — see Staging routing before Plex install below. Dispatcharr and qBittorrent appear in the card once they are installed and their services are running.

Plex remote access works at full bandwidth through VPN

When VPN app-routing is enabled for Plex, QuickBox automatically keeps port 32400 reachable on your server’s real public IP while routing Plex’s outbound calls through the VPN tunnel. Plex publishes the correct direct-connect address to plex.tv — your server shows as Reachable in your plex.tv account and clients connect directly without needing Plex Relay. See Plex — Remote access through VPN for full details.

Plex is system-wide

Because Plex runs as a single system-wide service (plexmediaserver), only one user can enable app-scoped routing for Plex at a time. Emby, Jellyfin, and qBittorrent use per-user template services, so multiple users can each have independent routing profiles.

Verify routing rules in Security Settings

When app-scoped routing is active, additional firewall rules are created for veth network namespaces and WireGuard interfaces. You can inspect these rules under Settings > Security > Firewall Rules tab by filtering on the WireGuard origin.

Staging routing before Plex install

Plex registers the server with your plex.tv account during its first connection after install. If that connection goes through the VPN, plex.tv records the VPN exit IP. If it goes over the direct connection, plex.tv records the real server IP.

To ensure Plex’s initial registration uses the VPN, you can stage routing before installing Plex. Staging sets up the VPN tunnel in advance so it is already in place when the install runs.

How to stage routing for Plex:

On the App-Scoped Routing card, select Plex from the app list. Plex appears in the list even when not installed.
Choose a tunnel backend, then pick a matching config from the dropdown — a WireGuard peer or an OpenVPN client tunnel.
Click Stage Routing (shown instead of “Enable Routing” when Plex is not yet installed).

The Plex row changes to a Staged · awaiting install pill — a sky-blue badge with a clock icon. This means the VPN configuration is ready and waiting. Kill switch settings and live metrics are not available at this stage.

Install Plex from Package Management (or via qb install plex -u username).

After the install completes, the routing profile automatically finalizes. The badge changes from Staged · awaiting install to Active (green). No manual step is needed.

Staging persists across reboots

If the server reboots between staging and installing Plex, QuickBox Pro re-establishes the staged VPN configuration automatically before the install begins. You do not need to re-stage.

Cancelling a staged profile

To cancel a staged profile before installing Plex, click Cancel Staging on the Plex routing row. This tears down the staged configuration and removes the routing profile.

For full guidance on why install order matters for Plex account registration, see the Plex application documentation.

qBittorrent-specific tuning

qBittorrent requires one additional setting when enabling app-scoped routing: the Peer Listen Port.

Why it matters: qBittorrent uses a dedicated port to accept incoming connections from other peers in a swarm. When qBittorrent is inside a private VPN tunnel, that port needs to be forwarded from the server’s public interface into the tunnel so that remote peers can reach it. The dashboard sets up this port forwarding automatically — but it needs to know which port you have configured inside qBittorrent itself.

What to do:

Open qBittorrent’s Web UI and go to Settings → BitTorrent → Listening Port.
Note the port number (or set one you want to use, in the 1024–65535 range).
Back in VPN Control, enter that same port number in the Peer Listen Port field before clicking Enable Routing.

Port must match

If the Peer Listen Port entered here does not match what qBittorrent is configured to use, incoming peer connections will fail. qBittorrent will report a “firewalled” or “not connectable” status, and your connectivity score in swarms will drop. If you need to change the port later, disable routing and re-enable it with the correct port.

qBittorrent WebUI access: Even though qBittorrent’s Web UI normally only listens on the local loopback inside the VPN tunnel, the dashboard handles the internal routing automatically so the /qbittorrent/ URL and the dashboard tile keep working without any action on your part.

Kill switch threshold: The default kill switch threshold for qBittorrent is 30 minutes — longer than the 10-minute default for media servers. Torrent sessions are long-lived, and brief WireGuard handshake stalls are common during normal operation. An aggressive threshold would trigger false-positive kill switch events and interrupt active downloads unnecessarily. You can adjust the threshold (between 60 seconds and 24 hours) in the kill switch settings panel after enabling routing.

For full guidance on routing qBittorrent through the VPN, see the qBittorrent application documentation.

Server configuration

The footer drawer shows your WireGuard server configuration:

Server keys — Public and private WireGuard keys for your server
Listen port — The UDP port WireGuard listens on
DNS settings — DNS servers configured for VPN clients
Peer statistics — Summary of total peers, active connections, and data transferred

Connection monitoring

The VPN Control page provides real-time monitoring of all VPN connections:

Data transfer stats — Bytes sent and received per peer
Connection history — View past connections and their duration
Active session tracking — See which peers are currently connected

Statistics update in real time via server-sent events.

CLI equivalents

Dashboard Action	CLI Command
Install WireGuard	`qb install wireguard`
Add a peer	`qb manage wireguard add`
Remove a peer	`qb manage wireguard remove`
Check VPN status	`qb manage wireguard check`

Dashboard advantage

The dashboard provides features not available via the CLI, including the geographic map visualization, NordVPN config generator, app-scoped routing management, and real-time connection statistics.

For the full WireGuard installation and CLI reference, see the WireGuard application documentation.

Best practices

Do

Enable the kill switch on routed apps to prevent unprotected traffic if the VPN drops
Use app-scoped routing to keep only relevant traffic on the VPN — this avoids unnecessary bandwidth overhead
Test your VPN connection by checking your public IP from a routed application after activation
Keep WireGuard configurations organized — use descriptive names for peers so you can identify them easily
Monitor data transfer stats to verify traffic is flowing through the VPN as expected

Don't

Don't activate a VPN peer without verifying the configuration file is correct — invalid configs can disrupt network connectivity
Don't route all applications through the VPN unless necessary — it adds latency and reduces throughput
Don't delete a peer configuration while it is actively routing app traffic — deactivate it first
Don't share your WireGuard private keys or configuration files — treat them like passwords
Don't assign the same .conf file to more than one routing slot — each active slot (system VPN or any routed app) needs its own distinct peer config with its own keys

FAQ

At least one VPN backend must be installed before VPN Control can function. Install WireGuard from Package Management or via qb install wireguard, or install OpenVPN from Package Management (a modal sets the listen port, protocol, client subnet, and pushed DNS) or via qb install vpn -u username. When both are installed, a WireGuard | OpenVPN selector appears at the top of the page.

Both are VPN backends you can manage from the page. WireGuard offers peer management, a NordVPN config generator, and server keys. OpenVPN offers server status, per-user profile viewing, and client-tunnel management (upload/activate/deactivate/delete). Both can serve as the tunnel backend for app-scoped routing — pick whichever your provider config is for. See the OpenVPN and WireGuard application docs.

Yes. Upload your provider's OpenVPN client config on the OpenVPN tab, then in the App-Scoped Routing card expand the app, choose the OpenVPN tunnel backend, select your config, and enable routing. Emby, Jellyfin, Plex, qBittorrent, and Dispatcharr are all routable through either backend, and the kill switch and health behavior are identical.

Only one system VPN peer can be active at a time. However, app-scoped routing operates independently — you can route multiple applications through the VPN simultaneously while also having a system VPN active. Each slot (system VPN + each routed app) requires its own distinct WireGuard peer config file.

Yes. A WireGuard config file represents a single authenticated session with the VPN provider — one keypair, one handshake. You cannot share a .conf file between two routing slots. If you want to route both Emby and qBittorrent, you need two separate .conf files (one per app), plus a third if you also have a system VPN peer active. All of them can point to the same VPN provider or server; they just need to be independent files with their own keys. Sharing a config will cause the second slot's handshake to fail, resulting in no connectivity and a Bad Gateway error.

The kill switch prevents an application from accessing the network if the VPN connection drops. This ensures that traffic from that application never travels over your direct internet connection unprotected.

Use the built-in NordVPN config generator on the VPN Control page. Select a country, and the dashboard generates a WireGuard-compatible configuration. Upload this config as a new peer to connect through NordVPN.

App-scoped routing supports five applications: Dispatcharr, Emby, Jellyfin, Plex, and qBittorrent. Installed applications appear in the routing card when their service is running. Plex also appears before it is installed so you can stage routing in advance. Dispatcharr routes its four application services (Gunicorn, Daphne, Celery worker, Celery beat) together in a single namespace — see the Dispatcharr VPN routing section for details. qBittorrent requires an additional Peer Listen Port setting when enabling routing — see qBittorrent-specific tuning above.

Stage Routing is shown when Plex is not yet installed. It pre-configures the VPN tunnel so that Plex's initial connection to plex.tv goes through the VPN during install. Enable Routing is shown when Plex is already installed and running — it immediately restarts Plex inside the VPN tunnel.

It means VPN routing for Plex has been configured and is waiting for Plex to be installed. Once you install Plex, the routing profile automatically becomes fully active and the badge changes to Active.

Yes — Plex remote access works at full bandwidth. QuickBox wires inbound client connections (port 32400) directly through your server's public IP while routing Plex's outbound API calls through the VPN. Plex publishes a reachable direct-connect address to plex.tv automatically, so your server appears as Reachable and clients connect without going through Plex Relay. See Plex — Remote access through VPN for details.

Allow up to two minutes for plex.tv to reflect the updated connection address. If it still shows unreachable, toggle VPN app-routing off and back on for Plex in the App-Scoped Routing card — this re-applies the routing configuration and re-publishes the direct-connect address. Restarting the Plex service from the dashboard also triggers a re-publish.

No. Any routing profile you have already enabled is restored automatically when the server comes back up — QuickBox Pro rebuilds each routing namespace and tunnel and restarts the routed services for you. Routed apps are held until their namespace is ready, so they no longer flap at boot. If an app looks briefly disconnected right after a reboot, allow a few minutes: a periodic safety-net check re-runs the recovery and converges on its own (worst case within about 15 minutes).

On the server. App-scoped routing runs the application inside a private network namespace on the QuickBox box, and that namespace's outbound traffic exits through the VPN. No one runs a VPN client on their own device for app routing. The exit location and egress IP shown for a routed app are where the app's traffic appears to originate (the VPN provider's exit point), not a user's device location.

No — this is expected. When app-scoped routing is active, the service runs inside a private network namespace. Its raw port (for example, 8096 for Emby) is no longer directly exposed on the server's public IP. Use the QuickBox reverse proxy instead: https://<your-server-or-domain>/<username>/emby/ works from anywhere and is the recommended access path. On your local network you can also reach the app at http://<server-LAN-IP>:<port> as normal. If you need the raw port reachable from the internet, you can set up a port-forward in your network separately — but most users do not need this when the reverse proxy is available.

WireGuard (Application)

Full WireGuard installation guide and CLI reference

OpenVPN (Application)

OpenVPN server install, client tunnels, and app-scoped routing backend

Plex — Remote access through VPN

Full-bandwidth Plex remote access when VPN routing is enabled — no Plex Relay required

Plex — VPN routing and account registration

Why install order matters for Plex when using VPN routing

qBittorrent — VPN routing

Peer listen port setup, kill switch tuning, and VPN routing for qBittorrent

Security Settings

View WireGuard firewall rules and verify network enforcement

SSL Certificates

Manage HTTPS certificates for your domains

System Monitoring

Monitor server health and network throughput

App Management

Install WireGuard and manage other applications

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support

Feature Previews

Community Configs

Active Discussions

Join Discord Server