Skip to content

Integrated WireGuard® server Pro

The integrated server is what makes Pro automatic: a small companion service (the sidecar) runs next to WireGuard® on your VPN host, and the backend uses it to create and remove VPN peers on its own. Once it's connected, activating a client is all it takes — no more manual .conf uploads.

You set up one integrated server per customer, on the machine that will actually carry that customer's VPN traffic.

Prerequisites

  • A running Pro backend with a valid license.
  • A Linux machine with Docker for the VPN itself — it needs a public IP or hostname reachable by your clients, and you'll open one UDP port on it. A small VPS or an on-premise box both work.

Steps

1. Create the customer

  1. In the admin panel, go to Admin → Customers → Add and create the customer.
  2. Open the customer and set Server mode to Valenius (integrated).
  3. Open the customer's Integrated Server tab and click Generate enrollment token. Keep this page open — the next steps use the download links and values it shows.

2. Prepare the VPN host

Log in to the VPN machine and run the preparation script, served directly by your own backend (no sign-in needed):

curl -fsSL https://vpn.example.com/api/download/prepare-sidecar-host.sh -o prepare-sidecar-host.sh
sudo sh prepare-sidecar-host.sh

This creates the WireGuard® configuration, generates the server's key pair, and enables IP forwarding. It prints the interface name and UDP port it used (defaults: wg99, UDP 51820) — note them.

3. Download the configuration and start the sidecar

  1. On the customer's Integrated Server tab, click Download .env — the file comes pre-filled with the right ports, your backend URL, and the one-time enrollment token. Copy it to the VPN host.
  2. On the VPN host, in the same folder as the .env file:
curl -fsSL https://vpn.example.com/api/download/docker-compose.deploy.yml -o docker-compose.deploy.yml
docker compose -f docker-compose.deploy.yml up -d
docker compose -f docker-compose.deploy.yml logs -f wg-sidecar

On first start the sidecar enrolls itself with your backend using the token and receives its certificates automatically.

4. Open the firewall

The Server status panel on the Integrated Server tab lists every port the VPN host needs, with the live values for this server:

Port Protocol Must be reachable from
WireGuard® port (e.g. 51820) UDP VPN clients, i.e. the public internet
Health port (e.g. 9004) TCP VPN clients — they check it before connecting
Management port (e.g. 9003) TCP Your Valenius backend only

Open them inbound on the host's firewall or cloud security group, and forward them if the host is behind NAT.

Never publish the management port

That port is how your backend administers this server. If your backend reaches the host over a site-to-site VPN you don't need to open it at all; otherwise restrict it to your backend's public IP address, which the panel shows you when it can't reach the server.

Don't skip this

Without the open UDP port, the setup looks healthy — the management connection works and tests pass — but no VPN tunnel will ever come up for a client.

5. Optional — fallback port

If your users are often on networks that block ordinary VPN ports (hotel and guest Wi-Fi, strict corporate egress), switch on Answer on a fallback UDP port under Server settings → Connection. The server then also answers on UDP 443, which such networks usually leave open. Both ports stay live, and the new one appears in the port list above so you can open it too.

Clients don't switch to it automatically yet — see Testing a server.

Verify it works

  1. On the customer's Integrated Server tab, click Check ports — every row should report Open.
  2. Click Run test in the Full configuration test card. This performs a real WireGuard® handshake against the server and asks it to check its own IP forwarding, NAT and routing. See Testing a server for how to read it.
  3. Activate any client assigned to this customer — its VPN peer and profile are created automatically, and the client can connect without you uploading anything.

Continue with First steps after install if this is your first setup.

Common problems

Enrollment fails in the sidecar log. The enrollment token is one-time and expires. Generate a fresh token on the Integrated Server tab, download a new .env, and start the sidecar again.

Test Sidecar succeeds, but clients never get a working tunnel. Almost always the UDP port (step 4) — the management path and the VPN path are separate. Check the firewall and cloud security group on the VPN host. Run test answers this directly: it performs a real handshake on the UDP port instead of leaving you to guess.

The tunnel connects but no traffic flows. The classic cause is IP forwarding switched off or a missing NAT rule on the VPN host — the tunnel comes up normally and then carries nothing. Run test checks both; see Testing a server.

The backend can't reach the server after setup. Enrolment runs outbound from the VPN host, the management API runs inbound to it — so a server that enrolled successfully but can't be reached afterwards is almost always a blocked inbound management port, not a broken install. The Integrated Server tab says so explicitly when it detects that combination, and shows the exact source address to allow.

The sidecar can't reach the backend. The .env contains your backend URL — the VPN host must be able to reach it over HTTPS. Test with curl -I https://vpn.example.com/ from the VPN host.

The admin panel warns about an overlapping transit network. Each integrated server's internal VPN subnet must be unique across all your customers. Pick a different subnet for the new customer — the warning banner on the Integrated Server tab explains which one collides.