Everything you need to deploy the backend, roll out clients, and — with Pro — wire up automated provisioning.
A Valenius deployment has two or three moving parts:
| Component | What it does | Edition |
|---|---|---|
| Backend | Admin panel, client registry, config distribution, update server. Runs as a Docker Compose stack. | Community |
| Clients | Windows, Linux, or macOS background service + tray/menu bar app, or the Android/iOS mobile app. Desktop clients are installed once with admin rights; used by everyone without them. | Community |
| Server sidecar | Runs next to your WireGuard® interface and lets the backend create and remove peers automatically. | Pro |
In the Community edition you upload existing WireGuard® .conf files in the admin panel and push them to devices. Pro removes that manual step entirely.
Ready-made installers for Windows, macOS and Linux are published at cloud.valenius.com/downloads, and the mobile app comes from Google Play. The source for all of it — backend and clients — is on GitHub, so you can build any component yourself instead.
The backend runs anywhere Docker runs. Clone the repository from GitHub and run install.sh — it builds the image, generates secure random passwords, and starts the stack for you:
$ git clone https://github.com/valeniusvpn/valenius.git $ cd valenius $ chmod +x install.sh $ ./install.sh
It prints your admin login URL and credentials once the backend is up. Sign in there, complete the first-run setup, and configure OIDC and/or TOTP for sign-in. Client installers are served from the backend itself, so connected clients update automatically — typically within an hour, or immediately when you press Force update on a device.
Download the current installer from cloud.valenius.com/downloads.
The installer sets up two pieces: a Windows Service that runs with system privileges and manages tunnels, and a tray app that runs in the user’s session. Supported on Windows x64 and ARM64.
Install once as administrator — interactively or silently via your software distribution tooling. On first start, the client generates a persistent device identity and registers with your backend; a new device appears in the admin panel waiting for activation.
| Path | Purpose |
|---|---|
C:\ProgramData\Valenius\registration.json | Device identity. Deleting it creates a new identity that needs re-activation by an admin. |
C:\ProgramData\Valenius\users\<user>\ | Per-user WireGuard® configs, readable only by the system account. |
The Linux client mirrors the Windows behaviour with native primitives: a root daemon managed by systemd, and a GTK tray app in the user session. It is packaged as a .deb and uses only system packages.
Copy the current .deb link from cloud.valenius.com/downloads and substitute the version below:
$ curl -LO https://cloud.valenius.com/api/download/valenius_<version>_all.deb # apt pulls in the dependencies and starts the service: $ sudo apt install ./valenius_<version>_all.deb # then point it at your backend: $ sudoedit /etc/valenius/appsettings.json # logs: $ journalctl -u valenius -f
Runtime dependencies are wireguard-tools, GTK3/PyGObject, and the AppIndicator tray bindings — all installed from your distribution’s repositories.
The macOS client mirrors the Windows and Linux design: a background daemon holds the tunnel and admin rights, and a menu bar app is what your users actually see and click. Runs on both Apple Silicon and Intel Macs.
Copy the current .pkg link from cloud.valenius.com/downloads and substitute the version below. Install it from the command line as an administrator:
$ curl -LO https://cloud.valenius.com/api/download/Valenius-<version>.pkg $ sudo installer -pkg Valenius-<version>.pkg -target /
On first start the client registers with your backend and appears in the admin panel, waiting for activation — the same flow as Windows and Linux. Once installed, it keeps itself up to date from your backend; you only do this by hand for the first install.
Get the Android app from Google Play. The iOS app is not on the App Store yet — we’ll link it here as soon as it lands.
Android and iOS share one app codebase and one enrollment flow. Instead of installing with admin rights, a new device is bound to a customer by scanning a QR code — generated in the admin panel or printed onto a QR config card for handing to a user.
Once paired, the app behaves like the desktop clients: encrypted profile storage, live connection status, and — where Pro session MFA is enabled — TOTP or push-to-approve prompts before the tunnel connects. Both platforms keep one VPN profile active at a time, an OS-level limit rather than a Valenius one.
The Pro server sidecar is a small service that runs on the same host as your WireGuard® interface and exposes a management API to your backend — secured by mutual TLS with certificates issued by your backend’s internal CA.
Setup is a one-time, three-step process:
# 1. Prepare the WireGuard® interface config $ sudo mkdir -p /opt/wg-sidecar/wireguard # (fill in PrivateKey, ListenPort, Address) # 2. Enable IP forwarding (survives reboots) $ echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-wireguard.conf $ sudo sysctl --system # 3. Generate an enrollment token in the admin panel, # set it as an environment variable, and start: $ docker compose up --build -d
On first boot the sidecar enrolls against your backend with the one-time token and receives its certificate automatically. The token is consumed on use; to re-enroll (for example after a CA rotation), generate a new token in the admin panel.
One sidecar instance manages one WireGuard® interface — one customer VPN. Multiple customers on the same host run as separate instances on different ports and interfaces, fully isolated from each other. Peers are reconciled on startup, so a server reboot never loses configuration.
Once the sidecar is running, use the admin panel’s connectivity tools to confirm the setup before handing it to a customer: “Check ports” verifies every inbound port with a real WireGuard® handshake, and “Run test” has the server inspect its own IP forwarding, NAT, and firewall rules. You can also enable the fallback port from the same panel — the server then answers on both its primary port and UDP 443, and clients retry there automatically if the primary port is blocked.
Session MFA is configured per group in the admin panel: require a fresh TOTP code on every connection, or once per a configurable time window. Enforcement happens server-side in the sidecar — the WireGuard® peer itself stays blocked until the user authorizes the connection, so it can’t be bypassed by a client that skips the prompt.
Users enroll once by scanning a QR code in the Windows tray, Linux tray, or mobile app, then authorize each gated connection with a 6-digit code — or, using push-to-approve, by confirming a matching number on a second device with Face ID or a fingerprint.
If the sidecar is out of date or unreachable, gated peers stay blocked rather than being let through — MFA fails closed, not open.
The Raspberry Pi appliance ships pre-configured: plug it into the network, and it connects to the backend and serves as the site’s VPN entry point.
Updates are fully managed. The on-device update agent polls the backend for a target version, verifies the image checksum, starts the new version alongside the running one, health-checks it, and only then swaps production — watching it afterwards and rolling back automatically if it misbehaves.
For larger fleets, roll a new version out in rings — a small subset of appliances first, then the rest — so a bad build is caught before it reaches everyone.
Looking for deeper technical detail? The full technical documentation lives at documentation.valenius.com, and the source code on GitHub.
