Skip to content
wavemesh

Self-hosting

Install wave-mesh

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

Latest releases

Choose a version and download the package for your system directly from GitHub.

Synology DSM 7

For a DiskStation, download the matching `.spk` above. The DS920+ uses Intel/AMD (`x86_64`); for other models, choose according to the CPU.

  1. In Package Center, choose Manual Install, select the .spk, and start wave.
  2. In Control Panel → Task Scheduler, create a one-time custom task as root, enter /var/packages/wave/scripts/setup, run it, then delete the task.
  3. Open wave from the DSM main menu, enter the control server address, and approve the DiskStation through the link shown.

After a package upgrade, run the setup step again so the running service uses the new binary.

Full DSM guide on GitHub

Quick start

Your first wave in three steps

Source code and Kubernetes overlays are on GitHub.

  1. 1. Set up the serverClone the product repository, configure the Kubernetes overlay, and start the control server, relay and database.
  2. 2. Install the clientDownload the archive for your system above, extract it, and install the service.
  3. 3. Connect a deviceSign in to your control server and bring up the wave.
  1. Requirements

    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.

  2. Control server, relay and database

    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 .
  3. Set the STUN address

    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
  4. Create the first account

    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
  5. Install the client

    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
  6. Log in and connect

    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
  7. Names and certificatesoptional

    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'
  8. Services from a Kubernetes clusteroptional

    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 .
  9. Services on the open internet: the pieroptional

    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
  10. Updates

    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

Rather have it set up?

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