Available in NyxGuard 4.0.14

Multi-Site WireGuard VPN Client

Connect NyxGuard to private applications at remote offices, datacenters, homes, and cloud networks—without exposing those applications to the public internet.

Architecture

Private reachability with a strict security boundary

NyxGuard keeps privileged tunnel operations outside the web application and gives every remote site its own isolated WireGuard interface.

NyxGuard ManagerUnprivileged UI and API
→
VPN AgentNET_ADMIN + /dev/net/tun only
→
WireGuard TunnelEncrypted site-specific route
→
Remote LANPrivate gateway, server, or app
1

One profile per site

Each remote network receives a name, configuration, interface, routes, connection state, handshake, counters, and ping test.

2

Least-privilege sidecar

The manager never receives host networking privileges. Private keys remain in the restricted VPN volume and are never returned by the API.

3

Safe destination routing

NyxGuard validates profiles, removes unsafe DNS changes, blocks executable hooks, narrows full-tunnel routes, and rejects overlaps.

Before you begin

Plan every address before creating profiles

Provider choice does not matter. The remote peer may be Linux, pfSense, OPNsense, MikroTik, a hardware router, a VM, or another cloud.

Information required for each site

Public endpoint and UDP port
Remote WireGuard public key
Unique tunnel addresses
Remote LAN CIDR ranges
A private IP for testing
Return route or NAT decision
ValueExampleMeaning
Remote endpointvpn.branch.example:51820/UDPPublic address used only to reach the WireGuard peer
WireGuard server10.90.20.1/24Private tunnel address on the remote peer
NyxGuard client10.90.20.2/32Unique tunnel address assigned to NyxGuard
Remote LAN192.168.20.0/24The full network that NyxGuard may reach
LAN test target192.168.20.1A gateway or server inside the remote LAN
Gateway address is not the LAN. 192.168.20.1 is one host. The route normally entered in AllowedIPs or Remote networks is 192.168.20.0/24.
The customer does not need Azure or a special LAN. NyxGuard can route normal private networks such as 192.168.2.0/24, 10.40.0.0/16, or 172.22.5.0/24. The selected CIDR only needs to be unique from other VPN sites and networks already used by NyxGuard.

Verify the NyxGuard host can provide TUN

NYXGUARD HOST
test -c /dev/net/tun && echo "TUN ready" || echo "TUN missing"
Proxmox LXC needs hypervisor configuration. A restricted guest cannot load the Proxmox kernel module or create the permitted device itself. On the Proxmox host, run modprobe tun, add lxc.cgroup2.devices.allow: c 10:200 rwm and lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file to /etc/pve/lxc/<CTID>.conf, then restart the guest and rerun the NyxGuard updater. Without TUN, 4.0.14 keeps Manager online and skips only the VPN agent.
Remote site

Configure the WireGuard server or gateway

The remote peer must accept the tunnel and route traffic between WireGuard and the private LAN.

1. Install WireGuard on a Linux gateway

UBUNTU / DEBIAN
sudo apt update
sudo apt install -y wireguard
sudo install -d -m 700 /etc/wireguard
wg genkey | sudo tee /etc/wireguard/server.key | wg pubkey | sudo tee /etc/wireguard/server.pub
sudo chmod 600 /etc/wireguard/server.key

Never copy the server private key into NyxGuard. The client profile needs only the server public key.

2. Enable IPv4 forwarding

SYSCTL
echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-wireguard-forward.conf
sudo sysctl --system

3. Create the server profile

/etc/wireguard/wg0.conf
[Interface]
Address = 10.90.20.1/24
ListenPort = 51820
PrivateKey = SERVER_PRIVATE_KEY

[Peer]
PublicKey = NYXGUARD_CLIENT_PUBLIC_KEY
AllowedIPs = 10.90.20.2/32

4. Start it and open the endpoint

SERVICE + FIREWALL
sudo systemctl enable --now wg-quick@wg0
sudo wg show
# Permit the selected WireGuard port in the host firewall, router, and cloud firewall/NSG.
sudo ufw allow 51820/udp

Choose return routing or source NAT

A handshake alone does not provide LAN access. The remote gateway must forward packets and remote devices must know how to return traffic.

A

Routed return path

Add a LAN/router route for 10.90.20.0/24 through the WireGuard gateway's LAN address. This preserves the original VPN source IP and is preferred where routing can be managed.

B

Source NAT

Masquerade 10.90.20.0/24 when the LAN router cannot be changed. Remote hosts see the WireGuard gateway as the source, but replies work without a new LAN route.

C

Firewall policy

Permit forwarding from wg0 to the LAN interface and established return traffic. Also allow the actual application ports on the destination hosts.

EXAMPLE NAT — ADAPT eth0 TO YOUR LAN INTERFACE
sudo iptables -A FORWARD -i wg0 -o eth0 -j ACCEPT
sudo iptables -A FORWARD -i eth0 -o wg0 -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
sudo iptables -t nat -A POSTROUTING -s 10.90.20.0/24 -o eth0 -j MASQUERADE
Do not paste generic firewall commands blindly. Confirm the LAN interface, tunnel range, firewall framework, and persistence method for the remote gateway. pfSense, OPNsense, MikroTik, and cloud routers should use their native policy and NAT controls.
NyxGuard profile

Build, upload, and connect the client profile

Create a dedicated client peer on the remote WireGuard server, then upload only that client profile to NyxGuard.

Standard client configuration

branch-office.conf
[Interface]
PrivateKey = NYXGUARD_CLIENT_PRIVATE_KEY
Address = 10.90.20.2/32

[Peer]
PublicKey = SERVER_PUBLIC_KEY
Endpoint = vpn.branch.example:51820
AllowedIPs = 10.90.20.1/32, 192.168.20.0/24
PersistentKeepalive = 25
What NyxGuard validates: private and public keys are never shown back in the UI; DNS entries are safely ignored; executable PreUp/PostUp/PreDown/PostDown hooks are blocked; default routes must be narrowed to explicit remote CIDRs.
  1. Open VPN Client from the main NyxGuard sidebar.
  2. Select + Add VPN site. The site name is optional; when omitted, NyxGuard derives it from the filename.
  3. Choose one standard .conf client profile and confirm that the readiness indicator shows the selected file.
  4. If the profile contains 0.0.0.0/0 or ::/0, enter only the required private CIDRs in Remote networks.
  5. Select Validate and add VPN site, review the detected routes, then press Connect VPN.
  6. Confirm a recent handshake before testing a remote address.
Multi-site routing

Connect many sites—provided their networks are unambiguous

Public endpoints may differ or even share a provider. What matters for application traffic is that the internal destination networks do not overlap.

SiteEndpointTunnel clientRemote networkStatus
Head Officevpn.hq.example:5182010.90.10.2/32192.168.10.0/24Valid
Branch Officevpn.branch.example:5182010.90.20.2/32192.168.20.0/24Valid
Warehouse203.0.113.40:5182010.90.30.2/3210.40.0.0/16Valid
Overlapping LANs are intentionally blocked. If two sites both advertise 192.168.1.0/24, a normal destination route cannot determine which customer/site should receive the packet. NyxGuard also rejects a remote route that overlaps a network already attached to the Manager. Different public IP addresses do not fix an internal route conflict.

For overlapping customer networks, renumber one LAN, translate one site to a unique range at its gateway, or connect only one conflicting site at a time. A future policy-routing/network-namespace design may provide additional isolation, but 4.0.14 fails safely instead of risking traffic entering the wrong tunnel.

Validation

Test the tunnel in layers

A green Connected state is the beginning of validation, not the end.

1

Interface and route

Confirm the site shows its own interface, tunnel address, endpoint, and exactly the expected remote CIDRs.

2

Recent handshake

A recent handshake proves that the endpoint, keys, UDP path, and peer configuration are working.

3

Remote gateway ping

Test the WireGuard server or remote gateway address. NyxGuard rejects targets outside the selected site's routes.

4

LAN host ping

Test an address inside the remote LAN. Failure here usually indicates forwarding, NAT/return routing, or a firewall.

5

Application port

ICMP may be blocked even when TCP works. Verify the real destination and port before creating a Proxy Host.

6

Restart recovery

After the first successful connection, verify auto-reconnect by restarting the stack during a maintenance window.

Private applications

Use the remote private origin in Proxy Hosts

After the selected tunnel can reach the application, NyxGuard can proxy it without making the remote application itself public.

Example upstream

PROXY HOST ORIGIN
Scheme:   http
Hostname: 192.168.20.10
Port:     8080

Origin:   http://192.168.20.10:8080
  • Use the private IP reachable through that site's displayed remote network.
  • Test the actual application port from the NyxGuard host before publishing.
  • Do not append a UI path such as /web to the upstream unless the application explicitly requires it.
  • Apply certificates, access lists, and NyxGuard security controls just as you would for a local upstream.
No special proxy mode is required. The VPN agent shares NyxGuard Manager's network namespace, so nginx follows the WireGuard route automatically. Once the private IP and port pass testing, configure them exactly like a normal LAN upstream.
Troubleshooting

Diagnose from the endpoint toward the application

Use the displayed state and the first failed layer to narrow the problem quickly.

Agent unavailableRun the 4.0.14 general updater again. Confirm nyxguard-vpn-agent is running and inspect its logs. Pulling only the manager image is not sufficient.
Interface downConfirm the profile passed validation and select Connect. Inspect the agent log for an invalid key, address, endpoint, or interface error.
Waiting for handshakeVerify the public endpoint, UDP port forwarding/NSG, peer public keys, server service, and that the server peer permits the NyxGuard tunnel address.
Handshake, no gateway pingCheck the server's tunnel address, its local firewall, and whether that address is included in the client AllowedIPs.
Gateway works, LAN failsEnable forwarding, add firewall rules, and configure either a return route or source NAT on the remote WireGuard gateway.
Ping works, app failsTest the real TCP/UDP port, verify the service listens on the expected interface, and inspect destination-host and intermediate firewalls.
Target outside networksThe address is not inside the selected site's displayed CIDRs. Correct the profile/Remote networks or test the address under the site that owns that route.
Overlapping route rejectedRenumber or translate one remote LAN. NyxGuard will not install an ambiguous route that could send traffic to the wrong site.
Production deployment

Install or upgrade the complete 4.0.14 stack

The VPN feature uses two matching images. The standard scripts install both and keep the additional service persistent after reboot.

Fresh installation

BASH
curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/install.sh | sudo bash

Upgrade or repair

BASH · 4.0.14
curl -fsSL https://raw.githubusercontent.com/NyxCloudRO/NyxGuardManager/main/update.sh \
  | sudo env FORCE_TAG=4.0.14 NYXGUARD_AUTO_YES=1 bash

Verify all services

BASH
docker ps --filter name=nyxguard
docker logs --tail=100 nyxguard-manager
docker logs --tail=100 nyxguard-vpn-agent
The updater preserves the existing database, certificates, proxy configuration, and named data volumes. It installs or repairs the isolated VPN agent even if the manager already reports version 4.0.14.

Ready to connect your first remote site?

Install 4.0.14, plan unique networks, create a dedicated WireGuard peer, then follow the layered tests above.

Install NyxGuard 4.0.14