Stable
v0.17.0
For regular use
Nov 16, 2026
Synology DSM 7
Release on GitHubSelf-hosting
A wave consists of a control server with relay and database, which you run in your own Kubernetes cluster, and the client on every device. This guide walks through both.
Downloads
Choose a version and download the package for your system directly from GitHub.
Stable
For regular use
Nov 16, 2026
Synology DSM 7
Release on GitHubUnstable
Preview build for testing
Nov 16, 2026
Synology DSM 7
Release on GitHubFor a DiskStation, download the matching `.spk` above. The DS920+ uses Intel/AMD (`x86_64`); for other models, choose according to the CPU.
.spk, and start wave.root, enter /var/packages/wave/scripts/setup, run it, then delete the task.After a package upgrade, run the setup step again so the running service uses the new binary.
Full DSM guide on GitHubQuick start
Source code and Kubernetes overlays are on GitHub.
A Kubernetes cluster; a single server with k3s is enough. The cluster needs an ingress controller with TLS and a public IP address that accepts UDP on port 3478 for STUN.
Two names for the control server and the relay, for example control.example.com and relay.example.com.
Optionally a DNS zone you own, for device names and certificates. Cloudflare, Hetzner, IONOS and INWX are supported; without credentials it still works, and you add TXT records yourself.
Copy the prod overlay and adjust three places that belong together: the names in ingress.yaml, WAVE_BASE_URL and the STUN address in WAVE_RELAYS. Login links and redirects are built from WAVE_BASE_URL, so the name must match the ingress.
secret.env holds the database password and connection address. If the container images are private, a dockerconfig.json with read access to GHCR goes next to it. Both files stay out of Git.
$ git clone https://github.com/moellenbeck-digital/wave-mesh.git$ cd wave-mesh$ cp -r deployment/server/overlays/prod deployment/server/overlays/mywave$ cd deployment/server/overlays/mywave$ cp secret.env.example secret.env # fill in, mode 600$ kubectl apply -k .
The STUN address in WAVE_RELAYS must be an IP address, not a name. It is known once the relay's service has a public address. Enter it and apply the overlay again.
$ kubectl -n wave-mesh get svc wave-relay-stun
There is deliberately no sign-up page: the operator creates accounts. The command asks for the password twice, at least twelve characters.
$ kubectl -n wave-mesh exec -it deploy/wave-control -- \bun apps/control/src/admin.ts set-password you@example.com
The client is a single binary for Linux, macOS and Windows, each on amd64 and arm64. install copies it to /usr/local/bin, creates the group wave and starts the service and tray icon. Day-to-day use needs no sudo after that.
On Windows, extract the ZIP archive and run wave.exe install in a console with administrator rights.
$ tar xzf wave-linux-amd64.tar.gz$ sudo ./wave install
wave login names your control server and prints a link to log in. Then wave up connects, and wave status shows live which path reaches each device. A device can join as many waves as you like.
$ wave login https://control.example.com$ wave up$ wave status
Give a wave a DNS suffix you own, and its devices get names under it and, if you like, Let's Encrypt certificates. The provider is set once per wave; after that wave cert fetches the certificate on the device, and the service renews it on its own. The private key never leaves the device.
For a provider token the server needs WAVE_DNS_SECRET (32 bytes, base64) to store the token encrypted. The default is Let's Encrypt's staging directory; real certificates come with WAVE_ACME_DIRECTORY.
With the manual provider this works with any host, but then every renewal also needs a person to add the TXT record.
$ kubectl -n wave-mesh exec -it deploy/wave-control -- \bun apps/control/src/admin.ts set-dns-provider mywave cloudflare$ wave cert --hook 'systemctl reload caddy'
A connector brings a cluster's internal services into the wave without an inbound port. It joins with a reusable key. After that a plain Ingress with ingressClassName: wave is enough, and every device in the wave reaches the service by its name.
$ kubectl -n wave-mesh exec deploy/wave-control -- \bun apps/control/src/admin.ts auth-key mywave connector --reusable$ cd deployment/cluster/overlays/example$ cp secret.env.example secret.env # paste the key$ kubectl apply -k .
A device can make a name in the wave's pier zone (app.pier.wave.example.com) reachable from the internet, with no inbound port, fixed address or port forwarding. As the operator you run the pier node (image wave-pier) on a machine or in a cluster with a public address; an Ingress passes everything on TCP 443 through to it by SNI.
set-pier writes the DNS record *.pier.<domain> once through your wave's provider API, or names it if you maintain the zone by hand. allow-pier permits the pier per device; only then can its owner expose a name with wave expose. After deny-pier, a name is unreachable at once.
Treat the pier node like a bastion host: it is a member of the wave and has a public address. Run it on its own machine or in its own cluster, with nothing else there.
$ kubectl -n wave-mesh exec deploy/wave-control -- \bun apps/control/src/admin.ts auth-key mywave pier --reusable$ cd deployment/pier/overlays/example$ cp secret.env.example secret.env # paste the key$ kubectl apply -k .$ kubectl -n wave-mesh exec deploy/wave-control -- \bun apps/control/src/admin.ts set-pier mywave wave-pier-0 --ipv4 <public address>$ kubectl -n wave-mesh exec deploy/wave-control -- \bun apps/control/src/admin.ts allow-pier mywave laptop
The service updates itself: the control server offers new releases, the client installs only what is signed with the release key, and rolls back on its own if the new build cannot reach a server. If you don't want to wait, install right away.
$ wave version$ wave update
We install wave-mesh in your company's cloud, connect clusters and devices and, if you like, take care of updates and operations.
See pricing