Run Relay on macOS

Overview

Viaalink Relay runs on macOS as a standalone binary (viaalink-relay) for Intel Macs (amd64) and Apple silicon Macs (arm64). It runs in the foreground in your user session: it keeps working while you are logged in and stops when you quit it or log out. While the Mac sleeps, the Relay cannot be reached.

For a Relay that should stay reachable around the clock, use a machine that is always on — see Run Relay on Linux, Run Relay with Docker, or Run Relay on Synology or QNAP.

Download

The macOS archives (Intel and Apple silicon) are published with the first release — ask contact@viaalink.com for early access.

Install

1. Extract the archive for your Mac (darwin-amd64 for Intel, darwin-arm64 for Apple silicon). It unpacks into a single folder that contains the viaalink-relay binary.
2. Move that folder to a permanent location, for example ~/viaalink-relay.

Clear the Gatekeeper quarantine

The binary is not notarized by Apple. When you download it with a browser, macOS marks it as quarantined and Gatekeeper refuses to run it (“cannot be opened because the developer cannot be verified”). Remove the quarantine mark from the binary once:

cd ~/viaalink-relay
xattr -d com.apple.quarantine viaalink-relay

If xattr reports that there is no such attribute, the file was not quarantined and you can continue. Then check that the binary runs:

./viaalink-relay --version

Configuration and data paths

Create the data folders and a configuration file in the Relay folder:

mkdir -p ~/viaalink-relay/keys ~/viaalink-relay/pubkeys ~/viaalink-relay/ssl ~/viaalink-relay/license

Create ~/viaalink-relay/config.yml (replace /Users/you with your home folder; launchd does not expand ~):

domain: relay.example.com
ssh-address: :2222
http-address: :8080
https-address: :8443
authentication: true
bind-random-subdomains: true
private-keys-directory: /Users/you/viaalink-relay/keys
authentication-keys-directory: /Users/you/viaalink-relay/pubkeys
https-certificate-directory: /Users/you/viaalink-relay/ssl
license-key-file: /Users/you/viaalink-relay/license/license.jwt

Back up the whole ~/viaalink-relay folder to keep your host keys, approved keys, and license.

Run the Relay

cd ~/viaalink-relay
./viaalink-relay --config ./config.yml

On first start the Relay generates a setup code, logs the setup link that contains it, and writes the code to license/setup-token.txt. Open the setup dashboard on the same Mac:

http://localhost:8080/_relay/dashboard?x-authorization=<setup-code>

Restart after changing settings

Some settings saved in /_relay/dashboard (ports, domain, HTTPS, IP and country rules) take effect after a restart. To apply them, the Relay stops itself gracefully and expects a supervisor to start it again. Run in a terminal, it simply exits — start it again by hand. Under the launchd agent below (with KeepAlive), launchd starts it again for you.

Start at login with launchd (example)

The Relay does not install a launchd job itself. The following is an example of a generic launchd user agent that starts the Relay when you log in and starts it again whenever it exits. It runs only while you are logged in.

Create ~/Library/LaunchAgents/com.viaalink.relay.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.viaalink.relay</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/you/viaalink-relay/viaalink-relay</string>
    <string>--config</string>
    <string>/Users/you/viaalink-relay/config.yml</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/Users/you/viaalink-relay</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/Users/you/viaalink-relay/relay.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/you/viaalink-relay/relay.log</string>
</dict>
</plist>

Load it into your login session, and unload it when you no longer want it:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.viaalink.relay.plist
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.viaalink.relay.plist

The log ends up in ~/viaalink-relay/relay.log, including the setup link on first start.

Firewall and router ports

If the macOS firewall is on (System Settings → Network → Firewall), macOS may ask on first start whether viaalink-relay may accept incoming connections; allow it.

On your router, forward 2222/tcp to the Mac and translate external port 80 to 8080 and 443 to 8443. If you enable calls through firewalls, also forward 3478/udp and 49152–49167/udp. See Requirements and Network Architecture for the full port table.

Next steps

• Authorize client keys in Access Control and Security.
• Activate a paid plan in Relay Licensing.
• Review every flag in Relay Configuration Reference.