Skip to content

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.

Shell
curl -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:

Shell
curl -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:

Shell
curl -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.

Shell
removent-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:

Shell
removent-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

Shell
sudo 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:

Shell
sudo 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.

  1. 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.
  2. On the controller, choose Add connection → Removent → Connect through relay → VPS / QUIC.
  3. Enter the address, room, client credential, relay fingerprint, and target Mac fingerprint from your verified client profile.
  4. 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:

ComponentLog 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 CLIlogs/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:

Shell
bash 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.