RemoScreen Relay Deployment Guide

What the relay does

Devices try a direct connection first. When that is unavailable, a relay forwards screen, audio and input data for authorized sessions. Add your relay under Connection services on both Mac and iPad to use it as a fallback. All download, configuration and startup steps here concern the relay.

Download and preparation

Choose Linux x86_64 or ARM64 for your server. The package should contain remoscreen-service, remoscreen-setup, templates, this guide, version and source identifiers, and SHA256SUMS. Compare the downloaded file with the checksum on the release page, then extract it into a new version directory and retain the previous version.

Prepare a Linux server, a domain resolving to it and a valid HTTPS certificate matching that domain. Use a dedicated account with minimal privileges and a persistent data directory. Make programs executable; restrict the state directory to that account and generated key files to mode 0600.

Examples use connect.example.com, HTTPS port 8443 and relay TCP port 9443. Check your domain, ports, firewall and cloud security groups first. If a port is occupied, plan a reverse proxy or separate listening address; do not replace an existing service.

Initialize the fallback relay

Run setup as the service account. Replace the example domain and use a separate data directory owned by that account:

./remoscreen-setup -directory /var/lib/remoscreen/relay \
  -role relay -name RemoScreen \
  -control-url https://connect.example.com:8443/v2/control \
  -relay-host connect.example.com -relay-tcp-port 9443

Setup creates the service identity, client access key and configuration. Subsequent setup must retain the relay role and original address; existing identities are not overwritten. Do not delete state or regenerate keys to update the program.

Start the fallback relay

Use the same data directory and replace the certificate paths with actual PEM files readable by the service account:

./remoscreen-service -service-role=relay \
  -control-listen=:8443 \
  -control-tls-certificate=/etc/remoscreen/fullchain.pem \
  -control-tls-key=/etc/remoscreen/privkey.pem \
  -service-info-config=/var/lib/remoscreen/relay/service-info.json \
  -relay-control-config=/var/lib/remoscreen/relay/relay-control.json \
  -relay-access-keys=/var/lib/remoscreen/relay/relay-access-keys.json \
  -control-revocation-store=/var/lib/remoscreen/relay/revocations.json \
  -control-primary-lock=/var/lib/remoscreen/relay/primary.lock \
  -account-deletion-journal=/var/lib/remoscreen/relay/deletion-journal.json \
  -usage-ledger-store=/var/lib/remoscreen/relay/usage.jsonl \
  -public-host=connect.example.com -tcp-relay-listen=:9443 \
  -tcp-require-local-control-allocation=true \
  -relay-node-id=self-hosted -relay-region=self-hosted \
  -require-commercial-subscription=false

Check startup in the foreground before using a Linux service manager. The service unit must use the dedicated account, absolute executable paths, the same arguments, private data directory and a restart-on-failure policy. Restart this service after certificate renewal to load the renewed certificate.

Add it on Mac and iPad

Read the private client-connection.json on the server to obtain the service address and client access key. Share them only through a trusted channel. On each device, open Connection services → Add server, enter the address and key, verify the service identity and save.

Importable client settings must come from the app's Export configuration action. client-connection.json is setup output for administrators, not an app import file. Never share service-info.json, relay-control.json, TLS private keys or the full server data directory.

Devices still try direct connections first. This fallback is used only when relaying is allowed and a direct connection is unavailable.

Verify deployment

From another network, check the HTTPS certificate and signed identity at /v2/service-info, then run the in-app server connection check. Using already authorized devices and a test network where direct access is unavailable, connect and confirm that this relay is actually used. Check logs for certificate or access-key errors.

A running process or successful health response does not prove full functionality. Check the actual remote screen, keyboard, mouse, file transfer and reconnection. Confirm that the server reports the delivered version.

Update, roll back and uninstall

Before updating, back up configuration, all persistent data and the previous binaries, and record the current version. Stop the relevant service, switch to the new version, retain the data directory and identity, and repeat the deployment checks. If it fails, stop the new version and restore the previous version with its matching backup. Follow that release's migration instructions for data-format changes.

To uninstall, disable and remove the relevant service unit first. The administrator must explicitly decide whether to remove program files and data. Preserve persistent data and backups by default; never remove another service's or app's data.