WireGuard VPN

Kernel-fast VPN tunnels with QuickBox CLI + dashboard control

WireGuard® on QuickBox Pro provides a lightweight VPN tunnel for routing server or application traffic through trusted endpoints. The QuickBox integration covers CLI automation, dashboard uploads, automatic MTU tuning, NAT rules, and stored keys for visual status. It includes app-scoped routing for isolating specific application traffic (Dispatcharr, Emby, Jellyfin, Plex, and qBittorrent) through WireGuard tunnels using Linux network namespaces. It also includes a server gateway that lets your box act as a multi-user WireGuard server — administrators enroll individual users, who connect their own devices into the box and (optionally) route all of their traffic through it. Plan firewall and routing rules accordingly for any additional traffic policies.

Installation

Prerequisites

Install via qb (CLI)

# Server setup with one client profile and NAT rules
qb install wireguard -u username -o server -lp 51820 -noc 1 -dns 1.1.1.1 \
  -cidr 10.5.0.2/16 -cai "0.0.0.0/0,::/0" -ep vpn.example.com \
  -pur "iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE" \
  -pdr "iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE"
 
# Client-mode installer (paste config when prompted)
qb install wireguard -u username -o client
 
# Reinstall in place (keeps stash under /etc/v4-dashboard/wg)
qb reinstall wireguard -u username -o server
 
# Remove WireGuard entirely
qb remove wireguard -u username

Install from the dashboard (VPN Control)

1. Open System → VPN Control (admin only).
2. Click Install WireGuard → choose Client (upload .conf) or Server (enter listen port, client count, CIDR, allowed address, endpoint, DNS, PostUp/PostDown).
3. Submit. Uploaded configs are written to /etc/v4-dashboard/wg/, server builds land in /etc/wireguard/ and are synced back to the stash.
4. Use the peer table to toggle Active (starts/stops wg-quick@<name>), view ping/location, and delete peers.

Basic Usage

Activate or swap a profile

# Sync a stored config to /etc/wireguard and start the service
qb manage wireguard check -cn nvpn_us1234
 
# Stop and remove the active client config
qb manage wireguard check --deactivate -cn nvpn_us1234
 
# Remove a stored profile and its service unit
qb manage wireguard remove -cn nvpn_us1234

• Dashboard: toggle the Active checkbox for a peer in VPN Control to start/stop wg-quick@<peer>. Location, ping, and redacted config preview come from /etc/v4-dashboard/wg/<peer>.conf and the cached IP lookup.
• CLI: qb manage wireguard check rewrites /etc/wireguard/<peer>.conf, enables wg-quick@<peer>, and updates user_software.software_alt_port so the dashboard stays in sync.

Add client or server configs (CLI)

# Add a client profile (paste config when prompted)
qb manage wireguard add --client -cn wg-client
 
# Add a server profile with custom CIDR, allowed IPs, and port
qb manage wireguard add --server -lp 51820 -cidr 10.5.0.2/16 \
  -cai "0.0.0.0/0,::/0" -noc 3 -pur "iptables -A FORWARD -i %i -j ACCEPT" \
  -pdr "iptables -D FORWARD -i %i -j ACCEPT"

NordVPN config generator (built-in helper)

# Generate up to 5 NordVPN WireGuard profiles (stores as nvpn_<host>.conf)
nvpn_conf_gen -t "<nordvpn_token>" -c "United States" -L 5 -dns 103.86.96.100
 
# List available countries
nvpn_conf_gen -l
 
# MTU tuning is automatic per endpoint (calls qb manage wireguard calc --mtu internally)

Configuration locations

CLI options

Common workflows

• Install + generate server peers: qb install wireguard -u username -o server -noc 3 ... writes wg0.conf and wg{n}-client.conf into the stash; use VPN Control to download or activate a specific peer.
• Import a provider profile: Upload .conf in VPN Control or qb manage wireguard add --client -cn provider and paste; MTU is injected if missing and permissions are normalized.
• Activate/rotate endpoints: Use peer table toggle or qb manage wireguard check -cn <peer> to bring up a tunnel; use --deactivate to tear down before switching regions.
• Generate NordVPN sets: nvpn_conf_gen -t <token> -c "United States" -L 5 outputs nvpn_<hostname>.conf files ready for activation.
• Reinstall safely: qb reinstall wireguard -u username -o server refreshes binaries and configs while keeping the stash in /etc/v4-dashboard/wg.

App-scoped routing

WireGuard client configurations you upload to VPN Control are the underlay for app-scoped routing. The routing setup itself — selecting which app to route, enabling the tunnel, and configuring the kill switch — is managed from System → VPN Control. This section explains what app-scoped routing does; for the full workflow including staging routing before installing Plex, see the VPN Control documentation.

Two routing modes

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

Main VPN (peer activation) — Activating a peer in the VPN Control peer table (toggling the Active switch) starts a wg-quick@<peer> tunnel that routes all server traffic through that peer. Every connection from your server — the dashboard, SSH, running applications — exits through the VPN. This is a full-tunnel, server-wide configuration.

App-scoped routing — A separate feature that routes only one application’s traffic through a WireGuard tunnel using a private 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 with no interference between apps or the host.

Both modes can be active at the same time — but they must use different WireGuard peer configs.

App-scoped routing lets you send only a specific application’s network traffic through a WireGuard tunnel while all other server traffic uses the default route. Each routed app runs inside its own Linux network namespace with a dedicated WireGuard interface, so there is complete traffic isolation with no interference between apps or the host.

qBittorrent is also a supported routable app alongside the media servers. Routing qBittorrent through WireGuard keeps BitTorrent traffic private, prevents ISP traffic shaping on torrent transfers, and isolates that traffic completely from the rest of your server. qBittorrent requires an additional step: you must supply the Peer Listen Port that matches what qBittorrent itself is configured to use, so that the dashboard can set up the correct port forwarding through the tunnel. See qBittorrent — VPN routing for the full how-to.

Supported applications

How to enable from the dashboard

1. Navigate to System > VPN Control (admin only).
2. Upload WireGuard client .conf files — one per routing slot you plan to use. If you have a main VPN peer already active, you need an additional .conf for each app you want to route. Two apps cannot share one .conf; each needs its own independent config file with its own keypair.
3. Scroll to the App-Scoped Routing card.
4. Select the application you want to route. Dispatcharr, Emby, Jellyfin, and qBittorrent must be installed and their service running before they appear here. Plex appears in the list even before it is installed, so routing can be staged ahead of time.
5. If the app has multiple service instances (e.g., Emby installed for several users), select the instance.
6. Choose a WireGuard peer config from the dropdown. Select a config that is not already in use — by the main VPN or by another routed app. Each active routing slot (main VPN + each routed app) must use a distinct .conf file.
7. Click Enable Routing.

The dashboard shows a live health indicator once routing is active, confirming that the namespace, WireGuard interface, and routing rules are all in place.

Kill switch protection

The kill switch is an optional safety net that fully stops the routed application’s service if the VPN tunnel degrades. This prevents any traffic from leaking outside the VPN.

• Trigger threshold: Configurable between 60 seconds and 24 hours (default 600 seconds / 10 minutes for Emby, Jellyfin, and Plex; 1,800 seconds / 30 minutes for qBittorrent). The kill switch fires when the WireGuard handshake age exceeds this threshold.
• Auto-recovery: When enabled, the system attempts to restore VPN routing automatically after a kill switch event using exponential backoff (2 minutes, 4 minutes, 8 minutes, 16 minutes, 30 minutes) up to 5 attempts.
• Manual re-enable: If auto-recovery is disabled or all 5 attempts are exhausted, an admin must manually re-enable routing from VPN Control.

Configure the kill switch from the Kill Switch Protection panel that appears after routing is enabled for an app.

Reaching a routed service

App-scoped routing moves a media server’s outbound traffic through the VPN tunnel, but it does not remove your inbound access paths. Once routing is enabled you can still reach Emby or Jellyfin in two ways.

Local network (LAN). Any device on the same local network as your server can connect directly using the server’s LAN IP address and the app’s normal port — for example http://192.168.1.10:8096 for Emby. The network namespace is on the server; LAN-adjacent devices connect as usual.

QuickBox reverse proxy. The dashboard’s reverse proxy bridges into the namespace through an internal veth link. The app remains available at https://<your-server-or-domain>/<username>/<app>/ on port 443, same as when routing is off. This is the recommended path for browser access whether you are on LAN or remote.

Remote / WAN access. For access from outside your network, use the reverse proxy URL or your own domain pointed at the server. The app’s raw port (e.g., 8096 for Emby, 8920 for Jellyfin HTTPS) is not automatically exposed on your server’s public IP when the app is inside a namespace — remote clients should go through the proxy or a port-forward you explicitly configure.

How it works (overview)

1. A dedicated Linux network namespace is created for the app (e.g., qb_emby, qb_plex, qb_dispatcharr).
2. A WireGuard interface is configured inside the namespace using the selected peer config.
3. A veth pair bridges the namespace to the host so the reverse proxy can still reach the app.
4. The app’s systemd service is restarted inside the namespace.
5. All traffic originating from the app exits through the VPN tunnel. Incoming requests from the dashboard’s reverse proxy reach the app through the veth bridge.
6. When routing is disabled, the namespace is torn down and the service restarts on the normal host network.

A background health monitor polls every 30 seconds to verify the namespace, WireGuard interface, and routing rules are intact. If the kill switch is enabled and the tunnel handshake goes stale, the monitor takes protective action.

Routed apps come back automatically after a reboot

App-scoped routing survives a server reboot without manual intervention. When the box comes back up, QuickBox Pro rebuilds every routing namespace and tunnel and restarts the routed services for you.

• Apps wait for their namespace. Routed services are held until their network namespace exists, so they no longer race ahead of the tunnel and flap at boot. A routed app that started before its namespace was ready would otherwise fail with a “network namespace path” error — that ordering gate prevents it.
• Services start in parallel, without blocking the boot. Restarting the routed apps is fire-and-forget, so one slow app cannot stall the recovery of the others.
• Self-healing if a boot run stalls. The reconcile step has a generous timeout (up to 10 minutes for a multi-namespace rebuild) and retries on failure. A periodic safety-net timer re-checks routing shortly after boot and again on an interval, so a boot that was interrupted self-heals — worst case within about 15 minutes — with no action from you.

Server gateway (multi-user inbound server)

The server gateway is a separate capability from the two outbound modes above. Instead of your box dialing out through a provider, the gateway makes your box a WireGuard server that other devices connect into. An administrator enrolls individual users; each enrolled user gets a private address from the gateway pool and a personal config they install on their phone, laptop, or router to tunnel into the box.

Who can do what

The gateway has two clearly separated roles:

Admin: provisioning the gateway

An administrator drives the gateway lifecycle from System → VPN Control (or the equivalent qb commands):

1. Enable the gateway. This provisions the wg0 server interface, generates the server keypair, enables IP forwarding, applies the NAT rules, and brings wg-quick@wg0 up. It is idempotent — running it again on an already-provisioned gateway changes nothing.
2. Enroll a user. Enrolling allocates the user a private /32 from the gateway pool, generates a fresh keypair, records the peer, and writes a personal config that the user can download. Enroll is what makes a user appear in the peer list. Re-enrolling the same user reuses their existing address.
3. Revoke a user. Revoking removes the user’s peer from the live interface and the saved server config, frees their address back into the pool, and deletes their config. It is idempotent — revoking a user who was never enrolled is a no-op.

The enrolled-peer list shows each user’s allocated address and public key. Private keys are never displayed — they live only in the user’s downloadable config.

# Enable / ensure the server gateway (idempotent)
qb install wireguard -o gateway-enable
 
# Enroll a user — allocates a /32 and writes their personal config
qb install wireguard -o gateway-enroll --wg-user username
 
# Revoke a user — frees their address and deletes their config
qb install wireguard -o gateway-revoke --wg-user username
 
# List enrolled peers (username, address, public key — never private keys)
qb install wireguard -o gateway-list

Split vs full tunnel

The gateway has a server-wide tunnel mode that controls how much of each enrolled user’s traffic routes through the box. Only an administrator can change it, and it applies to every enrolled user.

# Switch the gateway-wide tunnel mode (full or split)
qb install wireguard -o gateway-mode --wg-tunnel full
qb install wireguard -o gateway-mode --wg-tunnel split

User self-service: download and metrics

Provisioning is always done by an administrator. Once an administrator has granted a user access to the WireGuard app through their ACL group, a compact self-service panel appears in that user’s own Applications page. What the user sees depends on what the admin has set up for them:

• Download their own gateway config — once an admin has enrolled them on the server gateway, the WireGuard app row’s expansion panel shows a download button for their personal .conf. The download is scoped to the signed-in user only — no one can pull another user’s config, and there is no way to select a different user.
• View their own connection metrics — the panel shows their peer’s last handshake age and bytes transferred when they are connected. This is a snapshot that refreshes on an interval; it is display-only.
• See their routed apps and toggle their own routes — for any app an admin has routed for that user over WireGuard, the panel lists the app with its exit location, transfer totals, a health indicator, and a per-route Routed / Direct switch. That toggle is the one change a non-admin may make, and only on a route the admin already provisioned — a user can never provision a new route, change the backend, or touch another user’s route.

If an administrator has not yet enrolled the user or routed any app for them, the panel shows that nothing has been provisioned yet. Users never see the VPN Control page itself — that surface is admin-only. A user’s only WireGuard surface is the self-service panel in their own WireGuard app row, and only when their ACL group grants them the WireGuard app.

Security notes

• Each enrolled user gets their own keypair and a unique /32 from the gateway pool — peers are isolated from one another.
• Private keys are generated on the server and written only into each user’s downloadable config (640 permissions). They are never displayed in the peer list, never logged, and never emitted to the terminal. The peer list shows public keys and addresses only.
• In full-tunnel mode an enrolled user’s default route is redirected through the box, so all of that user’s Internet traffic exits from the server’s IP. In split-tunnel mode only traffic destined for the gateway subnet uses the tunnel.
• Enrolled peers persist in the server config, so they survive a reboot or a wg-quick restart. Revoking a user removes their peer both live and from the saved config.
• The gateway pool (10.13.13.0/24) is dedicated and does not overlap the outbound provider range, the app-routing namespace range, or the OpenVPN client subnet.

Best practices

Troubleshooting

FAQ

Additional resources