VeloraMesh

Installation guide

One clean path from server to clients.

This page explains the practical flow for installing VeloraMesh v1.0.0-rc1 packages, starting services, joining a network, and verifying the tunnel.

The packaged defaults are api.veloramesh.com:2053 and edge.veloramesh.com:3478. Replace domains and ports during setup for self-hosted deployments.

1. Server

Install the control-plane API and UDP discovery edge on Ubuntu.

2. Network

Create a network name and join secret with the local server manager.

3. Clients

Join Windows, macOS, Linux, and Android clients to the same network.

4. Verify

Check peers, doctor output, ping, RDP, and LAN discovery.

Before you start

Root or sudo access on the Ubuntu server.
HTTPS domain and selected TCP port for the API: api.example.com:2053.
DNS-only edge domain and selected UDP port for discovery: edge.example.com:3478.
Server install local bind prompts ask for host and port separately; leave host blank for all interfaces and do not enter domains or URLs.
The installer asks for a default virtual IPv4 CIDR for new networks; avoid CGNAT 100.64.0.0/10 and common home LAN 192.168.0.0/16 ranges.
Let’s Encrypt or equivalent TLS fullchain and private key files.
Open the selected API TCP port and edge UDP port on the firewall.
For split API/edge installs, copy /var/lib/veloramesh/edge-ticket.key from the API host to the edge host over a trusted channel.
Use an elevated PowerShell session for Windows service installs.
Clear quarantine for macOS packages downloaded through browsers or remote desktop.
Grant VPN permission on Android and prefer unrestricted battery mode.

Self-hosted deployment model

API and edge roles are separate by design.

Use one Ubuntu host for lab installs, or split API and edge across hosts for hardened self-hosting.

The edge does not carry user data, is not a relay, and must not store sensitive network state.

Lab / personal test

The installer menu All-in-one option runs the API and UDP discovery edge services on one Ubuntu server. This is the fastest starting point for testing and personal use.

Recommended self-hosted setup

Run API-only on the API machine and Edge-only on the edge machine. The edge remains DNS-only while the API origin can be better protected.

Hardened setup

API runs behind Cloudflare/WAF or a similar proxy, while edge runs on an isolated VPS with only the selected UDP discovery port exposed.

Roles

The v1.0.0-rc1 server package supports all-in-one, API-only, and Edge-only install roles. Lab deployments can run both systemd services on the same Ubuntu host; hardened deployments copy the edge ticket key to a separate edge machine.

Control-plane API

https://api.example.com:2053

Manages networks, devices, memberships, policies, sessions, membership tickets, and peer lists.

UDP discovery edge

edge.example.com:3478/udp

Observes client public UDP endpoints. It carries no DB, admin endpoint, join secret, or peer list.

DNS and Cloudflare guidance

Record Proxy Reason
www / apex site Proxied The product site is normal HTTPS traffic and can use cache, WAF, and TLS protection.
api.example.com Proxied or controlled DNS-only The control plane is HTTPS. Proxy mode should be enabled only after TLS/SPKI and client behavior are tested.
edge.example.com DNS-only UDP discovery does not pass through the normal Cloudflare HTTP proxy. Use a separate VPS/IP for higher security.

Edge security contract

RC status

Payloads must be encrypted, authenticated, and opaque enough to avoid stable protocol fingerprints.
No plaintext magic, protocol marker, discovery ID, network ID, or device ID should be exposed.
Invalid packets should be silently dropped without useful error oracles.
Per-IP rate limits and UDP flood controls should be applied.
Logs should be minimal and must not contain sensitive data.
The edge should remain stateless and should not connect to the API database.
The edge should listen only on the required UDP port.

Firewall allowlist

After installation, the OS firewall and any cloud provider security group must expose the same ports. If API and edge are split, do not open unnecessary ports on the other host.

Ubuntu UFW

For lab installs on one host, open the selected API TCP port and selected edge UDP port. The values below are packaged default examples.

sudo ufw allow 2053/tcp comment "VeloraMesh API"
sudo ufw allow 3478/udp comment "VeloraMesh edge discovery"
sudo ufw status numbered

firewalld

On RHEL, CentOS, or Fedora based systems, define the same allowlist with permanent firewalld rules.

sudo firewall-cmd --permanent --add-port=2053/tcp
sudo firewall-cmd --permanent --add-port=3478/udp
sudo firewall-cmd --reload

Cloud firewall

If your VPS panel or cloud provider has a security group, open the same ports there too. In split deployments, each host should expose only its own required port.

API host: allow inbound TCP 2053
Edge host: allow inbound UDP 3478
Admin SSH: restrict TCP 22 to your IP

Ubuntu server install

The server package is one package with three install roles: all-in-one, API-only, and Edge-only. Lab setups may run API and edge on one Ubuntu host; high-security deployments should run the API and UDP discovery edge on separate machines.

Extract the package and choose a role

unzip -o veloramesh-v1.0.0-rc1-linux-amd64-server.zip -d veloramesh-server
cd veloramesh-server
sudo bash ./manage-veloramesh-server.sh
  • Use linux-amd64-server for x86_64 Ubuntu, and linux-arm64-server for ARM64 Ubuntu/VPS/Raspberry Pi hosts.
  • For personal/lab installs choose 1) All-in-one API + Edge install/update.
  • Local bind prompts ask for host and port separately; leave host blank for all interfaces.
  • Use the default API port 2053 and edge UDP port 3478 unless your deployment needs different ports.
  • The installer asks for a default virtual IPv4 CIDR for new networks; press Enter to use 10.253.0.0/16.
  • Each new network can override that CIDR at creation time; existing network CIDRs are not changed in v1.
  • Do not enter domains or URLs here; public API and edge addresses are entered during client setup.
  • In a split-host topology choose 2) API-only on the API machine and 3) Edge-only on the edge machine.
  • Fresh/reset flows live under 4) Fresh/reset by role.

Hardened two-host flow

# API host
sudo bash ./manage-veloramesh-server.sh --setup --role api
sudo install -m 0600 -o "$USER" -g "$USER" /var/lib/veloramesh/edge-ticket.key ./edge-ticket.key
scp ./edge-ticket.key user@edge-host:/tmp/edge-ticket.key

# Edge host
# If prompted: Edge ticket key source path = /tmp/edge-ticket.key
sudo bash ./manage-veloramesh-server.sh --setup --role edge
sudo rm -f /tmp/edge-ticket.key
  • The Edge-only install carries no DB, TLS private key, join secret, or admin authority.
  • It uses only the edge-ticket.key copied from the API host through a trusted channel.
  • When Edge-only setup asks for "Edge ticket key source path", enter the temporary path on the edge host: /tmp/edge-ticket.key.
  • The installer places it under /var/lib/veloramesh/edge-ticket.key with the correct owner and permissions; delete the temporary /tmp copy afterwards.
  • It listens only on the selected UDP port.

Allow firewall traffic

sudo ufw allow 2053/tcp comment "VeloraMesh API"
sudo ufw allow 3478/udp comment "VeloraMesh edge discovery"
sudo ufw status numbered
  • If you do not use UFW, add the same rules in your server panel, security group, cloud firewall, or firewalld.
  • With split roles, open only the selected API TCP port on the API host.
  • Open only the selected edge UDP port on the edge host.

Verify services

/opt/veloramesh/veloramesh-server version
/opt/veloramesh/veloramesh-edge version
sudo systemctl status veloramesh-server --no-pager
sudo systemctl status veloramesh-edge --no-pager
sudo ss -ltnp | grep ":2053"
sudo ss -lunp | grep ":3478"
getent hosts edge.example.com
curl -i https://api.example.com:2053/v1/me
  • An unauthenticated empty 404 from /v1/me is expected.
  • Public API routes do not return product metadata without VeloraMesh request proof.
  • veloramesh-edge must be active and listening on the selected UDP port.
  • Clients enter edge host/domain and edge UDP port as separate fields.

Fresh install or reset

sudo bash ./manage-veloramesh-server.sh --fresh
  • Fresh removes the VeloraMesh data store, networks, members, and key material.
  • It does not touch Let’s Encrypt’s own directories.

Client installs

Windows service install

Extract the package that matches the device CPU architecture: Windows x86_64 or Windows ARM64. Use an elevated PowerShell session and answer yes to the background service prompt if the tunnel must run before user login.

Install

cd "C:\Path\To\veloramesh-v1.0.0-rc1-windows-<amd64-or-arm64>-client"
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-windows-client.ps1

Verify

$Client = "C:\Program Files\VeloraMesh\veloramesh-client.exe"
$Config = "C:\ProgramData\VeloraMesh\client.json"
& $Client network status -config $Config
& $Client network peers -config $Config
& $Client doctor -config $Config -network "network-name"

macOS LaunchDaemon install

Clear quarantine, make the files executable, and let the guided installer create the LaunchDaemon.

Install

cd ~/Desktop/veloramesh || exit
xattr -dr com.apple.quarantine .
chmod +x ./veloramesh-client ./install-macos-client.sh
sudo bash ./install-macos-client.sh --source-client ./veloramesh-client

Verify

sudo launchctl print system/com.veloramesh.client
sudo tail -n 80 /var/log/veloramesh-client.log
sudo /opt/veloramesh/veloramesh-client doctor -config "/Library/Application Support/VeloraMesh/client.json" -network "network-name"

Linux systemd client

The Linux client runs through TUN and systemd. Use linux-amd64-client on x86_64 systems and linux-arm64-client on ARM64 devices. The guided installer asks for API host/port, network name, join secret, and edge host/port as separate fields.

Install

unzip -o veloramesh-v1.0.0-rc1-linux-amd64-client.zip -d veloramesh-client
cd veloramesh-client
chmod +x ./veloramesh-client ./install-linux-client.sh
sudo bash ./install-linux-client.sh --source-client ./veloramesh-client

Verify

sudo systemctl status veloramesh-client --no-pager
sudo journalctl -u veloramesh-client -n 80 --no-pager
sudo /opt/veloramesh/veloramesh-client doctor -config /etc/veloramesh/client.json -network "network-name"

Android VPN client

Install the APK, enter API host/port, network name, join secret, and edge host/port. Trust the server identity, join the network, then prepare the VPN.

Install

API host/domain: api.example.com
API HTTPS port: 2053
Network name: your-network
Edge discovery host/domain: edge.example.com
Edge UDP port: 3478
Join secret: the secret from the server operator

Verify

Confirm the virtual IP in the app.
Check the notification peer count.
Ping or RDP to a Windows/Mac/Linux peer private IP.

Daily operations

Server manager

sudo bash ./manage-veloramesh-server.sh

Show network members

/opt/veloramesh/veloramesh-server admin --env /etc/veloramesh/veloramesh.env networks show -network network-name

Rotate join secret

/opt/veloramesh/veloramesh-server admin --env /etc/veloramesh/veloramesh.env networks rotate-secret -network network-name

Enable LAN discovery mode

/opt/veloramesh/veloramesh-server admin --env /etc/veloramesh/veloramesh.env networks broadcast -network network-name -mode all

IPv4/IPv6 underlay policy

/opt/veloramesh/veloramesh-server admin --env /etc/veloramesh/veloramesh.env networks underlay -network network-name -mode ipv4-only

Common cases

control plane returned status 401 / 404

The join secret may be wrong, membership may have been removed, or the device must rejoin the network. Stealth mode returns some unauthorized cases as silent 404.

control plane returned status 429

A valid client request was repeated too quickly. Wait briefly and retry; unauthorized or proof-invalid requests receive a silent 404 instead of 429 for privacy.

UDP discovery / edge is not working

Check the veloramesh-edge service, selected UDP listener, UFW/cloud firewall rule, and that the edge domain resolves DNS-only to the correct IP.

wintun.dll is missing

The Windows package was not extracted fully. wintun.dll must be beside veloramesh-client.exe.

macOS Operation not permitted

The package may be quarantined. Enter the package directory first, then clear quarantine and make the files executable.

cd ~/Desktop/veloramesh || exit
xattr -dr com.apple.quarantine .
chmod +x ./veloramesh-client ./install-macos-client.sh

Peer is connected but ping fails

Windows ICMP firewall may be closed. Test real services such as RDP or HTTP as well.

LAN games do not appear

If server broadcast mode is filtered, some discovery flows may not show. In trusted game rooms, try mode all.