Install Relay
Relay is published on the Resgrid Relay GitHub Releases page and as a Docker image. Every build is self-contained, so the machine doesn't need .NET installed.
Download
Each release has these files:
| File | Runs on | Modes |
|---|---|---|
ResgridRelay-Desktop-<version>-win-x64.zip, ResgridRelay-Desktop-<version>-win-arm64.zip | Windows 10 and 11: the desktop app | All five |
ResgridRelay-Console-<version>-win-x64.zip, ResgridRelay-Console-<version>-win-arm64.zip | Windows, headless | All five |
ResgridRelay-Console-<version>-linux-x64.tar.gz, ResgridRelay-Console-<version>-linux-arm64.tar.gz | Linux, headless (systemd unit included) | smtp, record, dispatch |
ResgridRelay-Console-<version>-osx-x64.tar.gz, ResgridRelay-Console-<version>-osx-arm64.tar.gz | macOS, headless (Intel and Apple silicon) | smtp, record, dispatch |
SHA256SUMS | Checksums of every archive | |
docker-image.txt | The Docker image tags and platforms built for the release |
Pick x64 for ordinary Intel and AMD machines and arm64 for Arm machines (a Windows on Arm laptop, a Raspberry Pi 4 or 5 running 64-bit Linux, an Apple silicon Mac).
The Docker image is resgridllc/resgridrelay, tagged with each version and with latest for the newest full release.
What's in the archives
| Archive | Contents |
|---|---|
| Desktop | ResgridRelay.exe, the LiveKit voice library livekit_ffi.dll, README.md, LICENSE.txt |
| Windows console | Resgrid.Audio.Relay.Console.exe, appsettings.json, a sample tone-detect watcher file settings.json, livekit_ffi.dll, README.md, LICENSE.txt |
| Linux console | Resgrid.Audio.Relay.Console, appsettings.json, settings.json, liblivekit_ffi.so, a systemd folder (unit file, environment example and notes), README.md, LICENSE.txt |
| macOS console | Resgrid.Audio.Relay.Console, appsettings.json, settings.json, liblivekit_ffi.dylib, README.md, LICENSE.txt |
The LiveKit library is what the voice modes (radio, record, dispatch) use to join Resgrid PTT channels. Keep it in the same folder as the executable: without it the voice modes can't start. It isn't part of the LiveKit NuGet package, so the release archives and the Docker image add it; if you build Relay yourself, build/fetch-livekit-ffi.ps1 in the Relay repository downloads the right one for your platform.
Verify the download
Check the archive against SHA256SUMS from the same release before you run it.
On Windows, in PowerShell:
Get-FileHash .\ResgridRelay-Desktop-2.1.50-win-x64.zip -Algorithm SHA256
Compare the hash with the line for that file in SHA256SUMS (the case doesn't matter).
On Linux or macOS, with SHA256SUMS in the same folder:
sha256sum --check --ignore-missing SHA256SUMS # Linux
shasum -a 256 --check --ignore-missing SHA256SUMS # macOS
OK next to the file name means it matches. Don't run an archive whose hash doesn't match: download it again.
Windows: desktop app
- Download
ResgridRelay-Desktop-<version>-win-x64.zip(orwin-arm64) and verify it. - Unzip it to a folder of its own, for example
C:\ResgridRelay. Keeplivekit_ffi.dllnext toResgridRelay.exe. - Run
ResgridRelay.exe. The Dashboard opens with a getting-started checklist. - Connect Relay to Resgrid, set up your mode, and turn on Auto-start for it on the Operations screen.
Only one copy of the desktop app runs at a time. Starting it again tells you it is already running in the tray.
The desktop app keeps its files outside the program folder, so replacing the program folder never loses your setup:
| What | Where |
|---|---|
| Settings (shared with the console host) | %APPDATA%\Resgrid\Relay\relay.user.json |
| Desktop preferences (auto-start modes, tray, notifications) | %APPDATA%\Resgrid\Relay\desktop.json |
| Rotated Resgrid refresh token | %LOCALAPPDATA%\Resgrid\Relay\resgrid-token.json |
| Log files (one per day, kept 14 days) | %LOCALAPPDATA%\Resgrid\Relay\logs |
See Desktop app for the screens and launch options.
Windows: console host
Use the console host on a Windows machine that runs Relay without anyone signed in to watch it, or when you prefer a configuration file.
Download
ResgridRelay-Console-<version>-win-x64.zip(orwin-arm64), verify it and unzip it, for example toC:\ResgridRelay\console.Open PowerShell in that folder and list the commands and common settings:
.\Resgrid.Audio.Relay.Console.exe helpConfigure it in one of three ways (see Where settings come from):
- edit
appsettings.jsonnext to the executable; - set it up in the desktop app on the same Windows account, which saves
%APPDATA%\Resgrid\Relay\relay.user.json, a file the console reads too; - set
RESGRID__RELAY__environment variables.
- edit
Run the configured mode:
.\Resgrid.Audio.Relay.Console.exe runCtrl+Cstops it cleanly. Running the executable with no command is the same asrun.
The console host runs one mode per process: the one in Mode. To run two modes, start two processes, each with its own RESGRID__RELAY__Mode, its own refresh token and its own RESGRID__RELAY__Resgrid__TokenCachePath. Resgrid retires a refresh token when it is used, so two processes that share one token — or that run from the same folder and so share the default ./data/resgrid-token.json — knock each other out: the first to sign in invalidates the other's token, and it fails with invalid_grant (see Refresh token rotation).
The console writes its log to the terminal only. When you run it unattended, redirect the output to a file.
Exit codes
| Code | Meaning |
|---|---|
0 | Stopped cleanly (Ctrl+C, systemctl stop, docker stop). |
1 | The mode failed or faulted while running, or a command failed. Restarting may help. |
78 | A configuration error: a missing credential, a value that can't be read, or an unknown mode. The message says which setting; restarting won't help until it is fixed. |
A service manager or scheduled task can use these: the shipped systemd unit restarts the relay after 1 but not after 78. Docker's restart policies restart a container after any non-zero code, so a container with a configuration error keeps restarting: docker logs shows the reason.
Relay doesn't install itself as a Windows service. For an unattended Windows relay, use the desktop app with Start Relay minimized to the tray when I sign in to Windows and Auto-start (see Operations), with the PC set to sign in automatically, or start the console host from a scheduled task. A scheduled task that runs as another account doesn't see your %APPDATA% settings file: give that account its own settings, or use appsettings.json or environment variables.
The console has setup commands for the Windows-only modes (devices, monitor, tune, test-tx, profiles, setup). They are listed on the radio bridge and tone detect pages.
Linux with systemd
The Linux console runs the smtp, record and dispatch modes. The radio and audio modes need a Windows sound card and PTT interface: on Linux they stop with a "not supported on this platform" message.
The archive includes a hardened systemd unit (systemd/resgrid-relay.service), an environment file to copy (systemd/relay.env.example) and notes (systemd/README.md).
1. Prerequisites
The voice library needs libstdc++6, which every standard distribution has. On Debian or Ubuntu:
sudo apt-get install -y libstdc++6
2. Install the files
# A service account and folders
sudo useradd --system --no-create-home --shell /usr/sbin/nologin resgrid
sudo mkdir -p /opt/resgrid-relay /etc/resgrid-relay
# The program (use linux-arm64 on Arm)
sudo tar -xzf ResgridRelay-Console-<version>-linux-x64.tar.gz -C /opt/resgrid-relay
sudo chown -R resgrid:resgrid /opt/resgrid-relay
# The settings, which hold secrets: readable by root only
sudo cp /opt/resgrid-relay/systemd/relay.env.example /etc/resgrid-relay/relay.env
sudo chmod 600 /etc/resgrid-relay/relay.env
sudo nano /etc/resgrid-relay/relay.env
# The unit
sudo cp /opt/resgrid-relay/systemd/resgrid-relay.service /etc/systemd/system/
In relay.env, set RESGRID__RELAY__Mode and the Resgrid credentials, then the settings of your mode (SMTP, recorder or tone-out). Every setting is a RESGRID__RELAY__ environment variable; the settings reference lists them all.
3. Point the unit at the release binary
The release build is a single self-contained executable, so edit /etc/systemd/system/resgrid-relay.service and change ExecStart to run it directly:
ExecStart=/opt/resgrid-relay/Resgrid.Audio.Relay.Console run
The unit's default ExecStart (/usr/bin/dotnet ... Resgrid.Audio.Relay.Console.dll run) is for a build you publish yourself that relies on an installed .NET runtime.
4. Start it
sudo systemctl daemon-reload
sudo systemctl enable --now resgrid-relay
journalctl -u resgrid-relay -f
What the unit does for you
- Runs as the unprivileged
resgriduser and restarts the relay if it fails (Restart=on-failure), but not after a configuration error: those exit with code 78, which the unit doesn't restart (RestartPreventExitStatus=78), because restarting can't fix a missing credential or a bad value. The reason is injournalctl -u resgrid-relay; fixrelay.env, thensudo systemctl restart resgrid-relay. - Stops the relay gracefully: on
systemctl stopRelay finishes in-flight recordings and leaves the PTT channel before it exits (up to 30 seconds). - Gives Relay one writable folder,
/var/lib/resgrid-relay, and points the defaults there:Smtp__DataDirectory=/var/lib/resgrid-relay/smtp,Resgrid__TokenCachePath=/var/lib/resgrid-relay/resgrid-token.jsonandRecorder__LocalPath=/var/lib/resgrid-relay/recordings. Yourrelay.envcan override them. - Locks the rest of the system down (
ProtectSystem=strict,ProtectHome,PrivateDevicesand more). If you store recordings or the recorder log somewhere else, add that path toReadWritePaths=in the unit. - Creates files readable by the
resgriduser only: the token cache, raw messages and recordings hold credentials and dispatch content. - Listens on SMTP port 2525 with no extra privileges. To listen on port 25 directly, add
CAP_NET_BIND_SERVICEto bothCapabilityBoundingSet=andAmbientCapabilities=, or keep 2525 and forward port 25 to it in your firewall.
Under systemd, only the environment and appsettings.json normally apply: the service account has no desktop-app settings file.
Several modes on one Linux host
One service runs one mode. To run, say, the recorder and the tone-out on the same host, make a unit per mode, each with its own environment file:
sudo cp /etc/systemd/system/resgrid-relay.service /etc/systemd/system/resgrid-relay-record.service
sudo cp /etc/systemd/system/resgrid-relay.service /etc/systemd/system/resgrid-relay-dispatch.service
# In each copy, set EnvironmentFile=/etc/resgrid-relay/record.env (or dispatch.env)
sudo systemctl daemon-reload
sudo systemctl enable --now resgrid-relay-record resgrid-relay-dispatch
Give each unit its own RESGRID__RELAY__Resgrid__TokenCachePath (for example /var/lib/resgrid-relay/record-token.json) and its own refresh token, so the two processes never rotate the same token (see Refresh token rotation).
macOS
The macOS console runs the smtp, record and dispatch modes.
mkdir -p ~/resgrid-relay
tar -xzf ResgridRelay-Console-<version>-osx-arm64.tar.gz -C ~/resgrid-relay # osx-x64 on Intel Macs
cd ~/resgrid-relay
./Resgrid.Audio.Relay.Console help
./Resgrid.Audio.Relay.Console run
Configure it with appsettings.json in that folder or with RESGRID__RELAY__ environment variables. If macOS refuses to open the executable because it was downloaded from the internet, remove the download flag with xattr -dr com.apple.quarantine ~/resgrid-relay and try again. Relay doesn't ship a macOS service definition: for an always-on Mac, run it from a launchd job of your own, or use Docker.
Docker
The resgridllc/resgridrelay image runs the console host in a hardened, non-root Linux container, with the LiveKit library built in. It runs the smtp, record and dispatch modes, one per container, and is configured entirely with environment variables.
SMTP dispatch
docker run -d --name resgrid-relay-smtp --restart unless-stopped \
-p 25:2525 \
-e RESGRID__RELAY__Mode=smtp \
-e RESGRID__RELAY__Resgrid__BaseUrl=https://api.resgrid.com \
-e RESGRID__RELAY__Resgrid__ClientId=YOUR_CLIENT_ID \
-e RESGRID__RELAY__Resgrid__ClientSecret=YOUR_CLIENT_SECRET \
-e RESGRID__RELAY__Resgrid__RefreshToken=YOUR_REFRESH_TOKEN \
-e RESGRID__RELAY__Smtp__DepartmentAddressDomains__0=dispatch.example.org \
-e RESGRID__RELAY__Smtp__GroupAddressDomains__0=groups.example.org \
-v relay-data:/app/data \
resgridllc/resgridrelay:latest
The container listens on 2525; -p 25:2525 publishes it as the standard mail port on the host. Always mount /app/data: it holds the rotated refresh token and the list of messages already processed. Without it, a restart starts from a refresh token Resgrid has already retired, and the relay can't sign in.
Recorder and tone-out
docker run -d --name resgrid-relay-record --restart unless-stopped \
-e RESGRID__RELAY__Mode=record \
-e RESGRID__RELAY__Resgrid__ClientId=YOUR_CLIENT_ID \
-e RESGRID__RELAY__Resgrid__ClientSecret=YOUR_CLIENT_SECRET \
-e RESGRID__RELAY__Resgrid__RefreshToken=YOUR_REFRESH_TOKEN \
-e RESGRID__RELAY__Recorder__Channel=all \
-v relay-record-data:/app/data \
-v /srv/relay-recordings:/app/recordings \
resgridllc/resgridrelay:latest
docker run -d --name resgrid-relay-dispatch --restart unless-stopped \
-e RESGRID__RELAY__Mode=dispatch \
-e RESGRID__RELAY__Resgrid__ClientId=YOUR_CLIENT_ID \
-e RESGRID__RELAY__Resgrid__ClientSecret=YOUR_CLIENT_SECRET \
-e RESGRID__RELAY__Resgrid__RefreshToken=YOUR_SECOND_REFRESH_TOKEN \
-e RESGRID__RELAY__Tts__ServiceBaseUrl=https://tts.resgrid.com \
-e RESGRID__RELAY__DispatchVoice__Channel=default \
-v relay-dispatch-data:/app/data \
resgridllc/resgridrelay:latest
Give each container its own /app/data volume and its own refresh token. Recordings go to /app/recordings unless you set RESGRID__RELAY__Recorder__LocalPath; mount a host folder there, or use S3 storage (see Recorder). The container runs as a non-root user: make sure a mounted host folder is writable by it.
Docker Compose
services:
relay-smtp:
image: resgridllc/resgridrelay:latest
restart: unless-stopped
ports:
- "25:2525"
env_file: relay-smtp.env # RESGRID__RELAY__... lines, kept out of the compose file
volumes:
- relay-smtp-data:/app/data
volumes:
relay-smtp-data:
Other container settings
| Variable | Purpose |
|---|---|
TZ | Time zone of the container (default Etc/UTC); used in log timestamps. |
WAIT_HOSTS | Optional. The container starts Relay through docker-compose-wait, so WAIT_HOSTS=redis:6379 waits for Redis (or any host:port) to accept connections before starting. |
LOCLX_ENABLED, LOCLX_TOKEN, LOCLX_RESERVED_ENDPOINT | Optional LocalXpose tunnel for the SMTP port, for a host that can't accept inbound connections. See SMTP dispatch. |
Self-hosted Resgrid
A self-hosted Resgrid installation already includes this image as the optional relay service. See Self-hosted installation (Docker Compose) or Multi-server (Kubernetes) for turning it on, and SMTP dispatch for the settings.
Upgrading
Releases are numbered 2.1.<build>. The About screen and the console's version command show what you run.
- Desktop app: choose Quit from the tray icon menu (closing the window only hides it), replace the program folder's contents with the new zip, and start
ResgridRelay.exe. Settings, the token cache and logs live in%APPDATA%and%LOCALAPPDATA%, so they carry over. If you turned on sign-in start, it keeps pointing at the sameResgridRelay.exepath, so unzip the new version into the same folder. - Windows or macOS console: stop it, keep a copy of your
appsettings.json, replace the files, and put yourappsettings.jsonback. - Linux: keep your settings in
/etc/resgrid-relay/*.envrather than inappsettings.json; then upgrading issudo systemctl stop resgrid-relay, extract the new archive over/opt/resgrid-relay,sudo chown -R resgrid:resgrid /opt/resgrid-relay,sudo systemctl start resgrid-relay. The token cache and data in/var/lib/resgrid-relayare untouched. If the new archive'ssystemd/resgrid-relay.servicechanged, compare it with yours and keep yourExecStartedit. - Docker: pull the new tag and recreate the container with the same volumes (
docker compose pull && docker compose up -d).
Always replace the LiveKit library together with the executable: the two are built to match.
Uninstalling
On Windows, turn off Start Relay minimized to the tray when I sign in to Windows first (it adds an entry under HKCU\Software\Microsoft\Windows\CurrentVersion\Run), quit Relay, and delete the program folder. Delete %APPDATA%\Resgrid\Relay and %LOCALAPPDATA%\Resgrid\Relay to remove the settings, token and logs too. On Linux, sudo systemctl disable --now resgrid-relay, then remove the unit, /opt/resgrid-relay, /etc/resgrid-relay and /var/lib/resgrid-relay.