Skip to content

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.

  1. In the Oneleet Dashboard, go to Settings > General and find Agent install token. Only workspace admins see it.
  2. Click Create token, then copy the token. It’s shown only once.
  3. 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.

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.

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/bash
TOKEN="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 2
done
if "$CLI" status 2>/dev/null | grep -q "^Status: logged in"; then
exit 0
fi
printf '%s' "$TOKEN" | "$CLI" login --enrollment-token-stdin --preconfirmed

The 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.

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:

Terminal window
set -e
umask 077
cd "$(mktemp -d)"
chmod -N .
curl -fsSL -o Oneleet.pkg "https://api.oneleet.com/api/v1/agent/installers/macos"
printf '%s' "$TOKEN" > oneleet-install-token
installer -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:

Terminal window
printf '%s' "$TOKEN" | "/Applications/Oneleet.app/Contents/Resources/oneleet-daemon" set-install-token --stdin

With 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.

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.

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.

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.

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.