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

Open the WireGuard® UDP port inbound on the VPN host's firewall or cloud security group. The exact port is shown on the Integrated Server tab (read live from the sidecar, so it's correct even if you changed the default).

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.

Verify it works

  1. On the customer's Integrated Server tab, click Test Sidecar — it reports success.
  2. 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.

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.