Infrastructure

Run your own relay server

The VaultMesh relay helps devices reach each other across networks while forwarding encrypted payloads only. It does not decrypt vault data.

What the Relay Does

VaultMesh devices sync directly on local network whenever possible. When devices are on different networks (for example home and mobile data), a relay provides a rendezvous channel for encrypted sync traffic.

Privacy model: relay transport is untrusted and stateless. Clients communicate with protocol header X-VaultMesh-Protocol: 3. Relay nodes forward ciphertext and cannot read vault plaintext.

Download Relay Packages

Use official packages hosted on this site:

Linux x86_64
.tar.gz binary package
Download
Linux arm64
.tar.gz binary package
Download
macOS
.tar.gz universal package
Download
Docker Image
.tar image archive
Download

Quick Start (Binary)

# Linux/macOS example
tar -xzf vaultmesh-relay-linux-x86_64.tar.gz
cd vaultmesh-relay
chmod +x vault-relay

# Start relay on port 8080
./vault-relay --port 8080 --log-level info

# Start with TLS certificates
./vault-relay \
  --port 443 \
  --tls-cert /etc/ssl/certs/relay.crt \
  --tls-key /etc/ssl/private/relay.key

Quick Start (Docker)

# Load image archive downloaded from this site
docker load -i vaultmesh-relay-docker-image.tar

# Run container
docker run -d \
  --name vaultmesh-relay \
  -p 8080:8080 \
  vaultmesh-relay:latest

System Requirements

ComponentRequirement
OSLinux (x86_64 or arm64), macOS, or Windows Server
RAM64 MB minimum
DiskLess than 30 MB for binary and logs
NetworkPublic domain or static IP with inbound TCP port
TLSRecommended for production deployments

Configuration Reference

Configure relay using CLI flags or environment variables:

FlagEnv VariableDefaultDescription
--port RELAY_PORT 8080 TCP port to listen on
--bind RELAY_BIND 0.0.0.0 Interface address to bind
--tls-cert RELAY_TLS_CERT - Path to PEM certificate file
--tls-key RELAY_TLS_KEY - Path to PEM private key file
--max-connections RELAY_MAX_CONNECTIONS 1000 Maximum concurrent device connections
--session-ttl RELAY_SESSION_TTL 3600 Inactive session timeout in seconds
--log-level RELAY_LOG_LEVEL info error, warn, info, or debug

Connect VaultMesh Clients

  1. Open Settings - Sync - Relay in the desktop app.
  2. Enter relay URL, for example wss://relay.yourdomain.com.
  3. Save and use the same relay URL on all devices in the same vault.

Important: production deployments should use wss:// with TLS. Plain ws:// is for localhost testing only.

Systemd Service (Linux)

# /etc/systemd/system/vault-relay.service
[Unit]
Description=VaultMesh Relay Server
After=network.target

[Service]
Type=simple
User=vault-relay
ExecStart=/usr/local/bin/vault-relay --port 8080 --log-level info
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now vault-relay
sudo systemctl status vault-relay

Health Check

Use the health endpoint for uptime checks:

GET /health

{
  "status": "ok",
  "version": "1.0.0",
  "connections": 3,
  "uptime_seconds": 86400
}

Note: relay is a sync transport component, not a VPN or generic proxy. Keep access controls aligned with your deployment policy.

Support

For deployment help, contact free.huoshan@gmail.com. Include relay version, command flags, and relevant log snippets.