Skip to main content

Desktop agent

Updated

The desktop agent app was retired on August 6, 2026. The /download page and its 7-day organization enrollment tokens are no longer used to add devices. Install the agent from Endpoints → Install instead, as described below.

Install the agent from Endpoints → Install

One agent covers RMM, Defend, CMDB, and Backups. Which of those products it turns on comes from your organization's license, so you don't pick products when you install. You can also reach the same page from Install Agent on any device list or on Defend → Agents.

  1. Go to Endpoints → Install.
  2. Click Generate Installer Token.
  3. Pick the customer the device belongs to.
  4. Optional: set Max uses and Expires. Enter how many installs this token allows (minimum 1); if left blank it defaults to 25 installs and expires after 30 days.
  5. Click Generate Token. The Installer ready dialog opens.
  6. Copy the token now. It's shown only once.
  7. Choose the device's operating system and copy the install command, or download the package: .msi (Windows), .pkg (macOS), or .deb / .rpm (Linux).
  8. Run the command on the device as an administrator.

To stop a token from adding more devices, click Revoke next to it under Active Tokens on Endpoints → Install.

Silent install

For scripted or unattended installs on Windows and Linux, pass the installer token as THEONE_TOKEN:

# Windows (elevated command prompt)
msiexec /i TheOneAgent.msi /qn THEONE_TOKEN=<token>


# Linux (Debian / Ubuntu)
sudo THEONE_TOKEN=<token> dpkg -i theoneagent.deb

# Linux (RHEL / Rocky / Alma)
sudo THEONE_TOKEN=<token> rpm -i theoneagent.rpm

macOS (agent 1.1.118 or later): macOS doesn't pass THEONE_TOKEN through installer, so don't use it on a Mac. Write the token to the root-only file /var/root/theoneagent-enrollment.token first, then run the installer with no token on its command line:

# macOS (Terminal or your MDM script)
printf '%s' '<token>' | sudo sh -c 'umask 077; cat > /var/root/theoneagent-enrollment.token' && \
sudo installer -pkg TheOneAgent.pkg -target /

The installer picks up the token from that file, enrolls the Mac, and deletes the file. No setup window opens on the device, and the token isn't written to the agent's logs.

On Windows and Linux, always pass the token as THEONE_TOKEN; on macOS, use the token file above. Replace <token> with the token from the Installer ready dialog.

Supported platforms

  • Windows
  • macOS
  • Linux (.deb and .rpm packages)

Common questions

I still have devices that were set up with the desktop app.

To move a device onto the current agent, run the install command from Endpoints → Install on it. If a device appears twice afterward, submit a ticket.

My old script uses a token from /download and fails.

Tokens from /download are retired. Generate an installer token on Endpoints → Install and pass it as THEONE_TOKEN (Windows, Linux) or in the token file (macOS). See Silent install.

Does the agent update itself?

Not today. Automatic updates aren't available yet; The One Stack staff roll out agent updates. To update a device now, run the current install command from Endpoints → Install on it. It upgrades the agent in place.

Does the agent need a user to be signed in?

No. The agent runs as a system service whether or not anyone is signed in to the device.

Related articles