Skip to content

Setup

Add employees to your workspace (Admins only)
  1. Go to the Oneleet Dashboard.
  2. Click on the People tab.
  3. Make sure everyone you want to add is either a workspace member or an employee.

Use the OS-specific instructions below to install the Oneleet Agent on your devices.

Device setup is available in the Oneleet Portal whenever Oneleet Agent is enabled, including in workspaces without Compliance. Open Device in the portal to download the agent and connect your device. Policies and security training appear only when those features are enabled for your workspace.

Enabling Oneleet Agent also enables People Management and Integrations, so your administrators can organize device owners and manage connections without Compliance. MDM is an additional capability for managing devices; it is not required to use the agent for device security monitoring.

Each device belongs to one workspace. If you belong to several workspaces, your device reports to the workspace where you enrolled it. Joining another workspace doesn’t enroll your existing device there.

To move a device, ask an admin to remove it from its current workspace before enrolling it in the new workspace. For a Mac managed through Apple MDM, unenroll it from MDM before removing it. Archiving or blacklisting a device doesn’t release its workspace ownership.

If connecting the agent keeps failing even with a new enrollment token, the device may already belong to another workspace. Ask an admin of that workspace to remove it, or contact Oneleet support.

The Oneleet Agent updates automatically. The Latest or Outdated badge shows whether the installed agent version is up to date.

Minimum system requirements for the Oneleet Agent on macOS:

  • macOS 13 (Ventura)
  • 8 GB RAM
  1. Open the Oneleet Portal in your browser and log in.
  2. Click on the Devices tab to download the Oneleet Agent for macOS.

The above steps should have downloaded a .pkg file to install the Oneleet Agent on your Mac.

  1. Double-click on the .pkg file to install the agent.
  2. You can now search for Oneleet in Launchpad to launch the Oneleet Agent, or open it directly from the Applications folder.

After installing the Oneleet Agent, connect it to your workspace so it can start reporting on your device.

  1. Open the Oneleet Agent and click Connect this device. The Oneleet Portal opens in your browser.
  2. In the portal, click Connect this device. If your browser asks whether to open the Oneleet Agent, allow it.
  3. In the Oneleet Agent, check that the workspace and your name are right, then click Connect. If you don’t recognize the workspace, click Decline, which cancels the request.
  4. Approve the administrator prompt that appears. Connecting a device requires administrator rights on it.

If the Oneleet Agent doesn’t open, the portal shows an enrollment token instead. In the agent, click Already have a token?, paste the token, and click Connect. Each token works once and expires after 30 minutes. Click Connect this device in the portal again to get a new one.

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.

  1. In the Oneleet Platform, 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. Assign each one to the person who uses it from the device’s menu. 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, which works on any distribution. Add ?format=deb or ?format=rpm for a package.

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.

A macOS package can’t take arguments, so install the package, then give the token to the agent. Run this as root:

Terminal window
installer -pkg Oneleet.pkg -target /
"/Applications/Oneleet.app/Contents/Resources/oneleet-daemon" set-install-token --token "oneleet_install_..."

The agent is already running when you save the token, so it connects the device on its next try, within two minutes. Other users on the device can see the token in the process list while the second command runs. To avoid that, pipe it in with printf '%s' "$TOKEN" | ... set-install-token --stdin instead.

You can also put the token in a file named oneleet-install-token in the same folder as the package before installing it. 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 it from a script your MDM runs as root, in a private folder. For example:

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 the installer can’t save the token, or refuses a token file, 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’s only the case when the agent was installed by a 2.6.0 or later installer. 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.

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 How do I remove a device from my workspace?.

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.

  1. Stop the background service by running sudo launchctl stop oneleet-daemon
  2. Open Finder and go to the Applications folder.
  3. Locate the Oneleet app bundle.
  4. Drag the app to the Trash or right-click and select Move to Trash.
  5. Empty the Trash by right-clicking on the Trash icon and selecting Empty Trash.