Deploy the agent with your MDM
If you deploy the Oneleet Agent with your own MDM, such as Jamf, Kandji, Mosyle, or Intune, an agent install token connects every device to your workspace without anyone signing in on it. Your MDM installs the agent, then runs a script that connects it. MDM scripts run as root or SYSTEM, so people don’t need administrator rights on their devices.
You need Oneleet Agent 2.4.1 or later on macOS, 2.5.0 or later on Windows, and 2.4.6 or later on Linux.
If you use Oneleet MDM, your Macs don’t need an install token, because a Mac that enrolls in Oneleet MDM gets the agent installed and connected automatically.
Create the token
Section titled “Create the token”- In the Oneleet Dashboard, go to Settings > General and find Agent install token. Only workspace admins see it.
- Click Create token, then copy the token. It’s shown only once.
- Store it in your MDM, for example as a script variable or secret, and add it to the script below.
Devices connected with the token appear in Devices without an owner. From the device’s menu, assign each one to the person who uses it. Its agent stays connected when you assign it.
Download the installer
Section titled “Download the installer”Each operating system has a URL that always downloads the agent version we currently ship to all workspaces, so your MDM configuration keeps working across releases.
| Operating system | URL | Downloads |
|---|---|---|
| macOS | https://api.oneleet.com/api/v1/agent/installers/macos |
The .pkg package |
| Windows | https://api.oneleet.com/api/v1/agent/installers/windows |
The .msi package. Add ?format=exe for the setup .exe. |
| Linux | https://api.oneleet.com/api/v1/agent/installers/linux |
The install script, for distributions that use systemd or OpenRC. Add ?format=deb or ?format=rpm for a package, and &arch=arm64 for ARM devices. |
Run the script
Section titled “Run the script”Deploy the installer first, then run this script on each device. It waits for the Oneleet Agent to start, skips devices that are already connected, and connects the others. Replace TOKEN with your install token.
#!/bin/bashTOKEN="oneleet_install_..."CLI="/Applications/Oneleet.app/Contents/Resources/oneleet-daemon"
for attempt in $(seq 1 60); do "$CLI" status >/dev/null 2>&1 && break sleep 2doneif "$CLI" status 2>/dev/null | grep -q "^Status: logged in"; then exit 0fiprintf '%s' "$TOKEN" | "$CLI" login --enrollment-token-stdin --preconfirmed$Token = "oneleet_install_..."$Cli = "C:\Program Files\oneleet-agent\oneleet-daemon.exe"
for ($attempt = 0; $attempt -lt 60; $attempt++) { & $Cli status *> $null if ($LASTEXITCODE -eq 0) { break } Start-Sleep -Seconds 2}if ((& $Cli status 2>$null) -match "^Status: logged in") { exit 0 }$Token | & $Cli login --enrollment-token-stdin --preconfirmedexit $LASTEXITCODE#!/bin/bashTOKEN="oneleet_install_..."CLI="/usr/bin/oneleet-cli"
for attempt in $(seq 1 60); do "$CLI" status >/dev/null 2>&1 && break sleep 2doneif "$CLI" status 2>/dev/null | grep -q "^Status: logged in"; then exit 0fiprintf '%s' "$TOKEN" | "$CLI" login --enrollment-token-stdin --preconfirmedThe script exits with a non-zero code when the device can’t connect, so your MDM reports it as failed. A device that belongs to another Oneleet workspace isn’t connected.
Pass the token to the installer
Section titled “Pass the token to the installer”With Oneleet Agent 2.6.0 or later, you can pass the token to the installer instead of running the script. The agent connects the device as soon as it starts, and tries again every two minutes if the network isn’t up yet. Older versions install the agent without connecting it, and the Linux install script stops with an error, so connect devices with the script above until your installer is 2.6.0 or later.
Put the token in a file named oneleet-install-token in the same folder as the package, then install the package. The installer saves the token and deletes the file. The file has to be owned by root, with no group or other write permission and no extended access list. Symbolic links and hard links aren’t accepted. Create the file in a private folder from a script your MDM runs as root, like this one:
set -eumask 077cd "$(mktemp -d)"chmod -N .curl -fsSL -o Oneleet.pkg "https://api.oneleet.com/api/v1/agent/installers/macos"printf '%s' "$TOKEN" > oneleet-install-tokeninstaller -pkg Oneleet.pkg -target /If your MDM installs the package itself and you can’t place a file next to it, run this as root after the package is installed:
printf '%s' "$TOKEN" | "/Applications/Oneleet.app/Contents/Resources/oneleet-daemon" set-install-token --stdinWith Oneleet Agent 2.6.1 or later, you can pass --token "oneleet_install_..." instead of --stdin. Other users on the Mac can see the token in the process list while that command runs.
Write the token to a file in a new folder that only SYSTEM and administrators can open, then pass the file’s full path as the INSTALLTOKENFILE property of the MSI package. The installer saves the token and deletes the file. It accepts only a file owned by SYSTEM, the Administrators group, or the account running the installer, with no access-list entry allowing other accounts to change it. Symbolic links and hard links aren’t accepted. Run this as SYSTEM:
$ErrorActionPreference = "Stop"$Token = "oneleet_install_..."$Folder = Join-Path $env:ProgramData ("OneleetInstall-" + [guid]::NewGuid())New-Item -ItemType Directory -Path $Folder | Out-Nullicacls $Folder /inheritance:r /grant:r "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-544:(OI)(CI)F" | Out-Nullif ($LASTEXITCODE -ne 0) { exit 1 }$TokenFile = Join-Path $Folder "install-token"New-Item -ItemType File -Path $TokenFile -Value $Token | Out-Null$Install = Start-Process msiexec.exe -Wait -PassThru -ArgumentList "/i Oneleet.msi /qn INSTALLTOKENFILE=`"$TokenFile`""Remove-Item -Recurse -Force $Folderexit $Install.ExitCodeIn Intune, deploy the MSI as a Win32 app whose install command runs a script like this one, because a line-of-business app can’t write the file first. With the setup .exe, pass /S /INSTALLTOKENFILE= followed by the file’s path instead.
With an installer newer than 2.6.0, you can pass the token itself as the INSTALLTOKEN property, for example as your MDM’s install command, which runs as SYSTEM:
msiexec /i Oneleet.msi /qn INSTALLTOKEN=oneleet_install_...In Intune, that works for a line-of-business app too: add INSTALLTOKEN=oneleet_install_... to its command-line arguments. With the setup .exe, pass /S /INSTALLTOKEN=oneleet_install_.... Windows Installer hides the token in its logs, but your MDM may keep the install command in its own logs on the device.
Run the install script as root with --install-token-file, pointing it at a file that root owns, with no group or other write permission. Mode 0600 keeps other users from reading it too. Symbolic links and hard links aren’t accepted. The script deletes the file once it has saved the token:
curl -fsSL -o install-linux.sh "https://api.oneleet.com/api/v1/agent/installers/linux"sudo bash install-linux.sh --install-token-file /root/oneleet-install-tokenYou can pass the token itself with --install-token, but other users on the device can see it in the process list while the script runs.
If the installer refuses the token file or can’t save the token, it exits with an error, so your MDM reports the device as failed. On macOS and Windows, the agent is installed anyway.
When your MDM runs the installer on a device that’s already connected, the device stays connected and the agent discards the token. On Windows, that holds only if a 2.6.0 or later installer installed the agent. Running the installer over an agent that an older installer installed signs it out, even if the agent has updated itself since, and the token can’t connect it again until you delete the device, as described in Connect a device again. If the token was revoked, or replaced and its grace period has ended, the agent discards it too, so run the installer again with the current token.
Reinstall the agent
Section titled “Reinstall the agent”To reinstall or repair the agent, have your MDM run the installer again. You don’t need to uninstall it first. A device that’s already connected stays connected, apart from the Windows case described above.
Uninstalling with the macOS script in Uninstall with your MDM also removes the device’s saved login. If you install the agent again afterwards, the device has to be connected again, as described in Connect a device again.
Connect a device again
Section titled “Connect a device again”The token can’t connect a device whose agent has already checked in, or a device someone enrolled with their own sign-in, so someone with the token can’t take over a device that’s in use. If you wipe a device or reinstall the agent and the script reports that the device is already connected, delete the device from Devices, then run the script again. This creates a new device record, so assign it again afterwards. See Stop monitoring a device.
Assigning a device that already has an owner to someone else signs out its agent. The agent can take up to about 40 minutes to report that it’s logged out, and until then the script skips it. After that, delete the device from Devices, run the script again, and assign the new device record to the new person.
Replace or revoke the token
Section titled “Replace or revoke the token”Anyone with the token can add devices to your workspace, so treat it like a password.
- Replace token gives you a new token. Choose how long the current one keeps working, up to 7 days, so you can update your MDM scripts first.
- Revoke stops every install token of the workspace from connecting devices.
Replacing or revoking the token doesn’t disconnect devices that are already connected. The settings show when the token was last used and how many enrollments used it, including retries before a device first checks in.