Private relay
Deploy a private relay on Linux, macOS, or Cloudflare, with updates and local logs.
On this page
The relay carries encrypted native RVP traffic between networks. Device pairing, capability grants, and mutual TLS remain end to end. Your relay can observe endpoint IPs, room names, traffic timing, and sizes, but does not decode your desktop.
Install on a VPS
Use Linux x86_64 or ARM64 with systemd 247 or newer, such as Ubuntu 22.04+ or Debian 12+. The server needs curl and tar; it does not need a Rust toolchain or Docker.
Shellcurl -fsSL https://raw.githubusercontent.com/backrunner/removent/main/scripts/install_relay.sh | sh
The installer downloads a prebuilt binary, verifies SHA-256 and its version, then opens the native setup wizard. Enter your public address, such as removent://relay.example.com:48700, room, and optional source networks. Setup generates separate host and controller credentials and starts an unprivileged systemd service. Allow the selected UDP port in your VPS firewall.
The selected stable GitHub release must include relay binaries. Releases published before these assets are introduced cannot be installed with this command.
To review the script or install a specific version first:
Shellcurl -fsSL https://raw.githubusercontent.com/backrunner/removent/main/scripts/install_relay.sh -o install_relay.shsh install_relay.sh --version v0.1.9 --no-setupsudo removent-relay setup --address removent://relay.example.com:48700
Stable updates
Automatic updates, check-update, and rotating local relay logs were introduced in v0.1.5. The installer defaults to the latest stable release. To install the current stable version explicitly:
Shellcurl -fsSL https://raw.githubusercontent.com/backrunner/removent/v0.1.9/scripts/install_relay.sh | sh -s -- --version v0.1.9
Read the stable release notes and download. Restart an existing service after installation. Automatic updates are disabled by default and follow stable releases when enabled, including upgrading an earlier beta to this stable version.
Host a relay on a Mac
The same curl command installs a complete relay on macOS 13+, with one Universal binary for Apple Silicon and Intel. Run the installer as your normal login user. It requests sudo only when writing the binary to /usr/local/bin; setup and service management run without sudo.
Shellremovent-relay statusremovent-relay startremovent-relay stopremovent-relay restartremovent-relay logs --followremovent-relay enableremovent-relay disable
The user LaunchAgent starts at login and recovers after a crash. enable and disable affect future logins without interrupting an active relay. stop unloads the running job so launchd will not immediately restart it. Logout stops the relay; a sleeping Mac cannot forward traffic. Keep the Mac logged in and awake, and configure firewall access and router UDP forwarding when needed.
Private configuration, connection profiles, identity, and logs live in ~/Library/Application Support/removent-relay. This service is separate from the desktop app's background daemon and needs no screen-recording or accessibility permission. macOS profile export uses your own directory:
Shellremovent-relay checkremovent-relay fingerprintremovent-relay export host --output "$HOME/relay-host.toml"removent-relay export client --output "$HOME/relay-client.toml" --host-fingerprint VERIFIED_TARGET_MAC_FINGERPRINT
Repeat the installer to upgrade, then run removent-relay restart. Installation preserves credentials, identity, login startup preferences, and whether the service is stopped. uninstall removes the LaunchAgent while retaining data and the binary. Intel support here applies to the standalone relay; the desktop app has its own system requirements.
Manage a Linux service
Shellsudo removent-relay startremovent-relay statussudo removent-relay logs --followsudo removent-relay stopsudo removent-relay restart
Use enable and disable to control boot startup separately. Stopping a service does not disable its next boot startup. check validates the configuration; fingerprint prints the existing relay certificate fingerprint. Use sudo to read private configuration or make service changes.
Run the installer again to upgrade, then explicitly restart to run the new binary. Upgrades preserve configuration, credentials, and identity. Restarting disconnects active sessions. uninstall removes the service while retaining those files and the binary.
Connect your Macs
Linux setup creates private profiles in /etc/removent-relay; macOS uses the directory above. Both already contain the relay certificate fingerprint. Export them through the CLI:
Shellsudo removent-relay export host --output /root/relay-host.tomlsudo removent-relay export client --output /root/relay-client.toml --host-fingerprint VERIFIED_TARGET_MAC_FINGERPRINT
Replace VERIFIED_TARGET_MAC_FINGERPRINT with the full fingerprint from the target Mac's removent-cli identity output, verified through a trusted channel.
- Securely transfer the host profile into the target Mac's daemon data directory, available from the tray's Open Data Directory action. Set its owner to the Mac user and permissions to 0600, then restart the background service.
- On the controller, choose Add connection → Removent → Connect through relay → VPS / QUIC.
- Enter the address, room, client credential, relay fingerprint, and target Mac fingerprint from your verified client profile.
- Complete device pairing and approve access before leaving the host unattended.
Host and controller credentials are separate; distribute only the appropriate profile. The desktop stores relay credentials in macOS Keychain. Back up /etc/removent-relay and the contents of /var/lib/removent-relay on Linux, or the complete macOS relay directory, privately. Never regenerate the relay identity while continuing to use an old pin.
Updates and local logs
Enable or disable automatic updates
The relay can install signed stable releases automatically. This defaults to off. Edit /etc/removent-relay/server.toml on Linux or ~/Library/Application Support/removent-relay/server.toml on macOS:
TOML[updates]enabled = truecheck_interval_secs = 86400
Apply the change with sudo removent-relay restart on Linux or removent-relay restart on macOS. Enabled services check 30 seconds after starting, then at the configured interval, which must be 3600–604800 seconds. To disable automatic updates, set enabled = false and restart.
Downloads are checked against an Ed25519 release signature and SHA-256 hashes of both archive and binary. macOS also verifies Developer ID. The verified binary checks the existing configuration before restarting the relay, briefly interrupting connections. A failed check, download, or verification leaves the running version in place.
Manual checks and version selection
Manual checks work independently of the automatic-update setting. They do not download or install a binary:
Shell# Default macOS serviceremovent-relay check-update# Linux: read private configuration and the installed service versionsudo removent-relay check-update --config /etc/removent-relay/server.toml# Another instanceremovent-relay check-update --config /path/to/server.toml
The command reads accessible local service configuration by default; without it, the command compares the CLI's own version. The stable feed must provide signed relay-latest-<platform>.json manifests. v0.1.2 has no such manifests. Until the feed includes them, a check reports a fetch error without affecting forwarding.
Updates live under identity_dir/updates; the system CLI remains the launcher, so the background process needs no system-directory write permission. Disabling updates preserves the installed version, configuration, credentials, and identity. To downgrade, stop the service, disable automatic updates, back up and move aside identity_dir/updates, install the selected version, then start the service.
Log locations and retention
The relay's main log is identity_dir/logs/removent-relay.log. Default locations:
| Component | Log file |
|---|---|
| Linux relay | /var/lib/removent-relay/logs/removent-relay.log |
| macOS relay | ~/Library/Application Support/removent-relay/data/logs/removent-relay.log |
| Desktop client, daemon, client CLI | logs/removent.log, logs/removentd.log, and logs/removent-cli.log in the data directory |
Each file is limited to 8 MiB and retains three backups, .log.1–.log.3, for approximately 32 MiB per component. Log files use mode 0600. The ten most recent crash reports are retained separately. Find the desktop data directory using the tray's Open Data Directory, or override it with REMOVENT_DATA_DIR.
On macOS, removent-relay logs --follow follows the local relay log. On Linux, that command reads the systemd journal; rotating local files are also retained. Use sudo tail -F /var/lib/removent-relay/logs/removent-relay.log to follow the Linux file.
Cloudflare Containers
Cloudflare uses HTTPS / WebSocket on port 443. Initial infrastructure deployment requires a Containers-enabled account, Node 24+, Python 3.11+, and Docker able to build Linux amd64. Follow the Cloudflare deployment guide for the Worker and container setup.
Cloudflare deployment, lifecycle, and upgrades use the repository scripts and management API. Its dashboard provides infrastructure and logs; installing the native relay CLI is unnecessary. From the source checkout:
Shellbash scripts/relay/deploy_relay.sh startbash scripts/relay/deploy_relay.sh statusbash scripts/relay/deploy_relay.sh stopbash scripts/relay/deploy_relay.sh deploy
deploy rebuilds and deploys the container, leaving it stopped until an explicit start. Containers do not run the relay updater. Their disks are ephemeral; Cloudflare manages log retention. A stop through the script or management API persists; host retries cannot restart a stopped container. An enabled container can sleep while idle and wake for a controller. View container logs in Cloudflare's dashboard. Infrastructure charges follow your hosting provider's terms.
Configuration reference
The installation and configuration guide covers source allowlists, unattended installation, configuration files, upgrades, and standalone foreground operation. See the VPS reference for protocol and trust details.