Deploy ORelay to many computers

Install the ORelay Agent on a fleet with the tool you already use, and add each computer to your organization with an enrolment key. Nobody has to visit a computer, and nobody at one has to approve anything.

In the web viewer, owners and admins open Deploy to your fleet from the menu under their name, or from Add a computer. It makes the files below with your key in them and shows the steps for the tool you pick. This page is the whole guide: what the files do, every tool’s steps, and what to do when something goes wrong.

Before you start

Every script adds computers with an enrolment key. An owner or admin of your organization makes one in the web viewer under Enrolment keys, or with Make a new key on Deploy to your fleet. Enrolment keys come with the Pro, MSP and Enterprise plans.

A key has:

a use limit: how many computers can join with it;
an expiry, up to a year;
a group the computers go into, or none;
the systems it is for: Windows, Mac, Linux, or any. A computer names its own system, so this keeps a key to the computers it is meant for; it proves nothing about them;
what happens when a computer uses it: the computer joins straight away, or it waits under Waiting for approval on the Enrolment keys page until an owner or admin approves it, and joins by itself within a few minutes of that. A key with no use limit, or one that never expires, always waits.

The key is shown once, when it is made: ORelay keeps only a hash of it. Copy it then. If it is lost, make a new one.

If a key gets out

Anyone who has the key can add computers to your organization until it expires, is used up or is revoked. That is all it does: it opens no computer already in your organization, shows nothing in it and changes nothing. So for each rollout:

give the key a use limit and an expiry that fit the rollout, or make it wait for approval;
revoke it on the Enrolment keys page when the rollout is done (the computers it added stay);
look at what it did: every use is in the Audit log, and owners and admins are told as computers are added and when they wait for approval.

Where the key goes

The scripts never put the key on a command line, and never in their logs. Where it rests depends on the tool:

Tool	Where the key is	Who can read it
Intune	`orelay-key.txt` inside the .intunewin	Intune’s administrators; on each computer, only in Intune’s cache while it installs
Configuration Manager	`orelay-key.txt` in the source folder, on distribution points, and in each computer’s cache	ConfigMgr’s administrators and whoever can read the source folder; each cache until it is cleared
Group Policy	`orelay-key.txt` on a share that only computers can read, never SYSVOL or NETLOGON	Every computer in the domain, and the share’s administrators
Another Windows tool	`orelay-key.txt` beside the script, or the tool’s secret variable `ORELAY_ENROLMENT_KEY`	The tool’s administrators
Jamf Pro, Kandji, another Mac tool	In the script, on its `ORELAY_KEY` line	The console’s administrators; each Mac while the script runs
Linux shell script	A file you put in place with mode 600 and delete after, standard input, or `ORELAY_ENROLMENT_KEY`	root
Ansible	Ansible Vault, handed to the task on standard input, never logged	Whoever holds the vault password

On Windows the key is a file of its own so that it never appears in a PowerShell script: Windows can record the text of every script it runs (script block logging, event 4104), and many security baselines turn that on. The script hands the file to the agent as its standard input. Mac tools can only run a script’s text, so there the key is in the script; macOS keeps no such record of it.

What the scripts do

The script for each system is the same whatever the tool. It:

checks that it runs as SYSTEM or root, and that the computer can run ORelay;
looks at the agent’s own files to see whether the computer is already in ORelay. One in your organization is left as it is, and so is one in another organization: a script never moves a computer;
reads the key and checks it looks like one;
installs the agent if it is missing or older than 0.1.124. The installer is checked before it runs: on Windows its signature must be ORelay Studios LLC’s, on a Mac it must be signed with our Developer ID and notarized by Apple, and on Linux it must carry our package signing key’s signature. Windows uses the newest installer beside the script; otherwise the script downloads it from orelay.io, over https only;
joins, with orelay-agent join --code-stdin and the key on standard input. When ORelay cannot be reached or is busy, or the network is not up yet, it waits and tries again, longer each time;
waits for the computer to connect, and ends with 0.

Your own server’s settings, if you chose them in Deploy to your fleet (where agents connect, where installers come from, no automatic updates), go to the installer, so they apply to the computers a script installs, not to ones that already had ORelay.

Safe to run again

A computer already in your organization takes about a second, and nothing is used up. A computer that has joined but is not in yet, because it is still connecting or waits for approval, is left alone for 20 hours after it joined with a key that joins straight away, and 160 hours with a key that waits. After that the script joins it again. That counts as the same computer, not another use of the key, as long as its first try has not lapsed.

So while the key works, a computer in the tool’s scope that is taken out of ORelay is added again at the next run: see Taking a computer out.

Logs

Windows: C:\Windows\Temp\orelay-deploy.log, kept to about 1 MB; the installer’s own log is C:\Windows\Temp\orelay-msi.log.
Mac and Linux: /var/log/orelay-deploy.log, readable by root only.

Every line has its time, and the agent’s own lines start agent:. The last line of each run starts ORelay: and says how it ended; that is the line Intune, Jamf Pro and the others show. No log holds the key: the agent writes only its first five characters (“Joining with the code that begins ABCDE...”).

Exit codes

The same on every system. What to do about each is under Troubleshooting.

Code	Meaning
0	ORelay is installed and the computer is in your organization, or it has joined and is connecting or waiting for approval.
1	Something unexpected happened. The log says what.
2	Linux: the script was given an option it does not take.
10	The installer failed.
11	The installer is not ORelay’s, or its signature could not be checked. Nothing was installed.
12	The installer could not be found or downloaded.
20	There is no usable enrolment key: no key file, an empty one, or one that is not plain text.
21	The key will not add this computer: it is not valid, has expired, was revoked or is used up, or it is not for this computer. The log says why.
22	The computer could not join. The agent’s words are in the log.
23	The script was not run as SYSTEM, root or an administrator.
24	This computer cannot run ORelay.
25	The computer is in another ORelay organization. It was left as it is.
26	The computer joined, but the ORelay Agent service did not start.
27	This computer was copied from another that has joined ORelay, so it shares that computer’s identity.
1618	Windows: another installation is running. Intune and Configuration Manager try again by themselves.

Windows

For 64-bit Windows (x64), desktop or server. Every Windows tool uses the same files from Deploy to your fleet:

orelay-install.ps1Installs ORelay and joins. The key is not in it.
orelay-key.txtContains the enrolment keyThe key, alone, as plain text.
orelay-detect.ps1For Intune and Configuration Manager: tells them whether ORelay is installed and the computer is in. No key.

And the installer, ORelay-Agent-<version>-x64.msi, from orelay.io/download/windows (how to check it). Without it beside the script, each computer downloads it.

Group Policy Software Installation (assigning the MSI) cannot add a computer to your organization yet, so Group Policy runs the script at startup instead.

Intune

Written from Microsoft’s documentation; tell us if a step differs.

Make a folder named ORelay and put the installer, orelay-install.ps1 and orelay-key.txt in it.

Wrap it with Microsoft’s Win32 Content Prep Tool, from the folder above it:

IntuneWinAppUtil.exe -c .\ORelay -s orelay-install.ps1 -o .\ORelay-intunewin -q

In the Intune admin center: Apps, Windows, Add, Windows app (Win32). Choose orelay-install.intunewin.
App information: Name ORelay Agent, Publisher ORelay Studios LLC.

Program. Install command:

powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\orelay-install.ps1

Uninstall command:

powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\orelay-install.ps1 -Uninstall

Install behavior: System. Device restart behavior: No specific action. Return codes: keep the defaults.

Requirements: operating system architecture 64-bit (x64) only.
Detection rules: Use a custom detection script, orelay-detect.ps1. Run script as 32-bit process on 64-bit clients: No.
Assignments: Required, for a group of devices. Try a small group first.

The key travels inside the .intunewin, which Intune keeps encrypted, and is on each computer only while it installs.

Configuration Manager

Written from Microsoft’s documentation; tell us if a step differs.

Put the installer, orelay-install.ps1 and orelay-key.txt in a source folder Configuration Manager reads. Only its administrators and the site server should be able to read it: the key file lets any computer join your organization.
Software Library, Application Management, Applications: Create Application. Manually specify the application information: Name ORelay Agent, Publisher ORelay Studios LLC.

Add a deployment type: Script Installer. Content location: the source folder. Installation program:

powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\orelay-install.ps1

Uninstall program:

powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\orelay-install.ps1 -Uninstall

Detection method: Use a custom script to detect the presence of this deployment type. Script type PowerShell; paste orelay-detect.ps1.
User experience: Install for system; Whether or not a user is logged on; Hidden; Maximum allowed run time 30 minutes.
Return codes: keep the defaults (1618 is a fast retry).
Distribute the content, then deploy as Required to a device collection. Try a small collection first.

Each computer keeps a copy of the content, key file included, in its Configuration Manager cache until the cache is cleared. Revoke the key when the rollout is done.

Group Policy

Make a shared folder that only computers can read: on a file server, share a folder that Domain Computers can read and only administrators can change, with Users and Authenticated Users taken off it (commands that make it). Not SYSVOL or NETLOGON: every account in the domain can read those.
Copy into it orelay-install.ps1, orelay-key.txt and the installer. Without the installer, each computer downloads it from orelay.io.
In Group Policy Management, make a GPO, link it to the OU of the computers, and edit it: Computer Configuration, Policies, Windows Settings, Scripts (Startup/Shutdown), Startup. On the Scripts tab (not PowerShell Scripts), Add. Script Name:
```
powershell.exe
```
Script Parameters, with your share in place of \\fileserver\ORelay$:
```
-NoProfile -NonInteractive -ExecutionPolicy Bypass -File "\\fileserver\ORelay$\orelay-install.ps1"
```
In the same GPO: Computer Configuration, Policies, Administrative Templates, System, Logon, Always wait for the network at computer startup and logon: Enabled.
Optional, for Ctrl+Alt+Del at locked computers: Administrative Templates, Windows Components, Windows Logon Options, Disable or enable software Secure Attention Sequence: Enabled, Services (how it works).
Each computer installs ORelay and joins at its next start. To try one now, run gpupdate /force on it, then restart it. Its log: C:\Windows\Temp\orelay-deploy.log.

The script runs at every start; once the computer is in ORelay that takes about a second. A startup script can run before the network is fully up, so the script waits and tries again, and what is left is tried at the next start. While the key works, a computer in the OU that is taken out of ORelay is added again at its next start: move it out of the OU first.

On the file server, in PowerShell run as administrator (the share name ends in $ so that it is not listed when someone browses the server):

New-Item -ItemType Directory -Path D:\Shares\ORelay
New-SmbShare -Name 'ORelay$' -Path D:\Shares\ORelay -FullAccess 'BUILTIN\Administrators' -ReadAccess 'Domain Computers'
icacls D:\Shares\ORelay /inheritance:r /grant:r "SYSTEM:(OI)(CI)F" "BUILTIN\Administrators:(OI)(CI)F" "Domain Computers:(OI)(CI)RX"

The last line takes away the permissions the folder inherited, Users and Authenticated Users with them, and leaves SYSTEM and Administrators in full control and Domain Computers able to read. Group names are translated on Windows in other languages: use the names your domain has.

Another tool on Windows

Put orelay-install.ps1 and orelay-key.txt in one folder, on the computer or on a share it can read, and run this as SYSTEM or an administrator:

powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\orelay-install.ps1

If your tool hands secrets to scripts as environment variables, set ORELAY_ENROLMENT_KEY to the key and leave orelay-key.txt out. To remove ORelay, run it with -Uninstall.

Mac

For macOS 13 or later, on Apple silicon or Intel. Mac tools run a script’s text, so the key is in the script:

orelay-install-mac.shContains the enrolment keyInstalls ORelay and joins; the key is on its ORELAY_KEY line.
orelay-mac-check.shExits 0 when the Mac is in, for Kandji’s audit and tools that check first. No key.
orelay-jamf-ea.shA Jamf Pro extension attribute that reports how the Mac stands. No key.

The script downloads the installer from orelay.io and installs it only once Apple’s checks say it is signed by Developer ID Installer: ORelay Studios LLC (TG7B72KJQD) and notarized.

Jamf Pro

Written from Jamf’s documentation; tell us if a step differs.

Settings, Computer management, Scripts, New. Display name: ORelay: install and join. Paste orelay-install-mac.sh.
Policies, New. General: Trigger Recurring Check-in and Enrollment Complete; Execution Frequency Once per computer; Retry Event On next recurring check-in, Retry attempts 3.
Scripts: add ORelay: install and join, Priority After.
Scope: a test group first, then the Macs you want.
Optional, to follow the rollout: Settings, Computer management, Extension attributes, New: Data type String, Input type Script, paste orelay-jamf-ea.sh. It reports in, joining, elsewhere, not joined or not installed.
For remote desktop, add ORelay’s privacy profile as a configuration profile.

The key is in the script, which Jamf Pro’s administrators can read and which is on each Mac while it runs. If Jamf hosts the installer, add the package to the same policy: the script then only adds the Mac.

Kandji

Written from Kandji’s documentation; tell us if a step differs.

Library, Add new, Custom Script. Name ORelay. Execution frequency: Run every 15 minutes (nothing happens once the Mac is in).
Audit script: paste orelay-mac-check.sh.
Turn on Remediation script and paste orelay-install-mac.sh.
Assign it to a Blueprint; a test Blueprint first.
For remote desktop, add ORelay’s privacy profile: Library, Add new, Custom Profile.

The key is in the script, which Kandji’s administrators can read and which is on each Mac while it runs.

Another tool on a Mac

Run orelay-install-mac.sh as root, from the folder it is in:

sudo /bin/bash orelay-install-mac.sh

In Intune: Devices, macOS, Shell scripts; Run script as signed-in user: No; Max number of times to retry if script fails: 3. orelay-mac-check.sh exits 0 when the Mac is in, for tools that check first.

The Mac privacy profile

orelay-privacy.mobileconfig is a privacy (PPPC) profile for your MDM. It lets ORelay’s session helper, and only the one ORelay Studios LLC signed, use Accessibility, so remote input works, and lets a person at the Mac who is not an administrator allow Screen Recording. Apple lets no MDM grant Screen Recording itself, so someone at each Mac still clicks Allow once.

Only a supervised or user-approved MDM enrollment can install it. Upload it as it is: in Jamf Pro under Computers, Configuration Profiles, Upload; in Kandji as a Custom Profile.

Linux

For x86-64 computers with systemd, using apt or dnf. The packages are tested on Debian 12, Ubuntu 22.04 and 24.04, Fedora and Rocky Linux 9.

orelay-install.shInstalls ORelay and joins. The key is not in it.
orelay-key.txtContains the enrolment keyThe key, alone, as plain text.

The script downloads the package from orelay.io and installs it only once its signature checks out against our package signing key, fingerprint A86F D8DF 6BF6 01B8 E65C 7627 2781 1DE2 BE7A 3757.

With a shell script

Copy orelay-install.sh and orelay-key.txt to the computer, the key file readable only by root:
```
sudo install -m 600 orelay-key.txt /root/orelay-key.txt
```

Run the script, then delete the key file:

sudo bash orelay-install.sh --key-file /root/orelay-key.txt
sudo rm /root/orelay-key.txt

With Puppet, Salt or Chef: put the key file in place with mode 600, run the script as root, then remove the file; or pipe the key in with --key-stdin; or set ORELAY_ENROLMENT_KEY.

Ansible

Put orelay.yml and orelay-install.sh in one folder. Neither holds the key.
Keep the key in Ansible Vault:
```
ansible-vault encrypt_string --stdin-name orelay_enrolment_key
```
Paste the key, press Return, then Ctrl+D. Put what it prints in your group_vars.
Change hosts: all in orelay.yml to your group.
Run it with pipelining, so the key is never written to the computers’ disks while the task runs:
```
ANSIBLE_PIPELINING=True ansible-playbook -i <your inventory> orelay.yml --ask-vault-pass
```

The play shows each computer’s ORelay: line, and fails a computer that could not install or join with the script’s exit code. The task that carries the key is never logged, even with -vvv.

Golden images

Install ORelay after an image is deployed, not into it. A computer installed from an image that already had ORelay shares its identity with every other copy, and only one of them can be in ORelay; the scripts end the others with 27.

If an image has it: stop the ORelay Agent service and delete identity.json (and machine_key.pem and machine_cert.pem if they are there) from the agent’s data folder, then capture:

Windows: C:\ProgramData\ORelay\data
Mac: /var/db/orelay
Linux: /var/lib/orelay

Never capture a computer that has joined.

Taking a computer out

While the key works, the scripts add back any computer in the tool’s scope. To take one out for good, first take it out of the deployment (the Intune group, the collection, the OU, the Jamf Pro scope or Kandji Blueprint, your inventory), or revoke the key; then remove it in ORelay.

To uninstall the agent:

Windows: orelay-install.ps1 -Uninstall, which Intune and Configuration Manager run as the uninstall command:
```
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File .\orelay-install.ps1 -Uninstall
```
Mac: sudo /usr/local/share/orelay/uninstall.sh
Linux: sudo apt remove orelay-agent or sudo dnf remove orelay-agent

Uninstalling keeps the computer’s identity, so installing again brings back the same computer, still in your organization unless someone removed it there.

Troubleshooting

Start with the log (where it is): its last line says how the run ended, and the lines before it say why.

0: ORelay is installed and the computer is in your organization, or it has joined and is connecting or waiting for approval.: Nothing. If the computer is not on the Dashboard after a few minutes, see below.
1: Something unexpected happened. The log says what.: Read the log. If it does not say what to do, send us its last lines (they never hold the key) and we will look.
2: Linux: the script was given an option it does not take.: Run it with --key-file PATH or --key-stdin, or with the key in ORELAY_ENROLMENT_KEY. The script never repeats what it was given, in case it was the key.
10: The installer failed.: The installer’s own words are in the log; on Windows, also in C:\Windows\Temp\orelay-msi.log. Free disk space and an installation already under way (1618) are the usual causes.
11: The installer is not ORelay’s, or its signature could not be checked. Nothing was installed.: Download the installer again from Download and check it. Replace any old copy on your share. If ORelay’s signing certificate has changed since your files were made, scripts made before refuse newer installers: make the files again in Deploy to your fleet.
12: The installer could not be found or downloaded.: The computer has to reach orelay.io and downloads.orelay.io on port 443 (network requirements). On Windows you can put the installer beside the script instead.
20: There is no usable enrolment key: no key file, an empty one, or one that is not plain text.: Put orelay-key.txt back as Deploy to your fleet made it: the key alone, as plain text. Notepad’s “Unicode” (UTF-16) and a byte order mark make it unreadable.
21: The key will not add this computer: it is not valid, has expired, was revoked or is used up, or it is not for this computer. The log says why.: The log has the server’s reason. Make a new key, or raise this one’s use limit, under Enrolment keys. A computer that was turned away can be allowed again there.
22: The computer could not join. The agent’s words are in the log.: The agent’s words, last in the log, say why: the plan’s computer limit, too many computers waiting for approval (approve or turn some away), or ORelay out of reach after every try (network requirements).
23: The script was not run as SYSTEM, root or an administrator.: Run it as the tool’s system account (in Intune, Install behavior: System), as root on a Mac or Linux, or from PowerShell run as administrator.
24: This computer cannot run ORelay.: ORelay runs on 64-bit Windows (x64), macOS 13 or later, and x86-64 Linux with systemd and apt or dnf. On Windows Server Core, add App Compatibility first (below).
25: The computer is in another ORelay organization. It was left as it is.: The computer belongs to another ORelay organization, and no script moves one. To bring it into yours, remove it from the other organization first.
26: The computer joined, but the ORelay Agent service did not start.: Start the agent and read its log: Restart-Service ORelayAgent in PowerShell run as administrator, sudo launchctl kickstart -k system/io.orelay.agent on a Mac, sudo systemctl restart orelay-agent on Linux.
27: This computer was copied from another that has joined ORelay, so it shares that computer’s identity.: The computer was made from an image, or a virtual machine was cloned, after ORelay had joined. Give it an identity of its own: stop the ORelay Agent service, delete identity.json, machine_key.pem and machine_cert.pem from the agent’s data folder (Golden images), then run the deployment again. Reinstalling alone keeps the identity.
1618: Windows: another installation is running. Intune and Configuration Manager try again by themselves.: Intune and Configuration Manager try again by themselves. With another tool, run it again once the other installation has finished; Group Policy does at the next start.

Joined, but not on the Dashboard

The key waits for approval: the computer is under Waiting for approval on the Enrolment keys page until an owner or admin approves it.
The key is not for the computer’s system: it is refused when it connects, and the key’s history on the Enrolment keys page shows “Not allowed” and its system.
Your organization is at its plan’s computer limit.
The computer reached api.orelay.io on port 443 to join, but cannot reach agents.orelay.io on port 50051 to connect (network requirements).

Windows Server Core

ORelay needs Server Core’s App Compatibility feature. Add it, restart, and run the deployment again:

Add-WindowsCapability -Online -Name ServerCore.AppCompatibility~~~~0.0.1.0

PowerShell that runs only signed scripts

Where Group Policy sets PowerShell to AllSigned, or AppLocker or App Control for Business (WDAC) puts PowerShell in Constrained Language mode, orelay-install.ps1 cannot run as it is. Sign it with your own code signing certificate, or allow it by its path or hash in your policy.

The computer’s clock

A computer whose clock is far off cannot join: the certificates it is given look expired or not yet valid to it. Set it to the right time and run the deployment again.