The One Stack agent is a single installer. It turns a computer into a managed device for RMM, plus Defend, CMDB, and Backups if your organization licenses them. You install it once per device. Within about a minute the device checks in and starts reporting health data.
Where this happens: the Hub → Endpoints → Install
Installer tokens and install commands come from one page in the Hub, the MSP workspace at app.theonestack.com. Every Install Agent button in RMM, CMDB, and Defend opens that same page.
At a glance
| App | The Hub (app.theonestack.com). Sign in with your MSP account. |
|---|---|
| Page | Endpoints → Install |
| On the device | Administrator rights, plus outbound internet on port 443 |
| Systems | Windows (.msi), macOS (.pkg), Linux (.deb or .rpm). Chromebooks are handled differently: see Chromebooks. |
| Time | About 2 minutes per device. One token can cover a whole customer rollout. |
Ways to get to the installer
Each of these opens the same Endpoints → Install page, so start from whichever one you're already in.
| You're in… | Click | Direct link |
|---|---|---|
| The Hub | Sidebar Endpoints, then the Install tab | Endpoints → Install |
| The Hub, Endpoints → Devices | Install Agent | Endpoints → Devices |
| RMM | Sidebar Install Agent (right under All Devices) | RMM → All Devices |
| RMM setup | Sidebar Onboarding. The wizard sends you to the installer. | RMM → Onboarding |
| CMDB or Defend | Install Agent on the device or agent list | Opens Endpoints → Install |
Before you start
- On the device: administrator (Windows) or sudo/root (macOS, Linux) rights.
- Network: outbound HTTPS on port 443 is open. You don't need any inbound ports.
- Customer: know which customer the device belongs to. If they're new, you can create them on the install page.
Step 1: Generate an installer token (in the Hub)
- Open Endpoints → Install in the Hub.
- Under Generate Installer Token, fill in the form:
Field What to enter Customer Search by name or domain. Devices installed with this token join that customer automatically. To add a customer here, choose the create option, type a name, and click Create. Installing on your own MSP's machines? Leave the default internal option selected. Label (optional) A name you'll recognize later, such as Acme Corp – Windows Servers. Max Uses (optional) How many devices the token can enroll. Leave it blank and the token allows 25 installs. Enter a larger number for a bigger rollout. Expires (optional) The last day the token works. Leave it blank and the token expires after 30 days. Deployment Source (optional) How you'll push it, such as Intune, Group Policy, or Manual. This is for your records. - Click Generate Token. The Installer ready window opens and shows which customer you're installing to.
You don't choose products. The agent turns on whichever modules (RMM, Defend, CMDB, Backups) your organization is licensed for, and you can change modules later without reinstalling.
Copy the token now. It's shown only once. The install commands contain a live token for this customer. Treat them like a password: anyone who has one can add devices to that customer.
Step 2: Copy the command for the device's OS
In the Installer ready window, click Copy next to the right operating system, or download the package if you'd rather install it yourself.
| OS | Package | Where to run the command |
|---|---|---|
| Windows | .msi | PowerShell opened as Administrator (right-click → Run as administrator) |
| macOS | .pkg | Terminal. It asks for your password through sudo. |
| Linux, Debian or Ubuntu | .deb | A terminal, as root or with sudo |
| Linux, RHEL, Rocky, or Alma | .rpm | A terminal, as root or with sudo |
Step 3: Run it on the device
- On the device, open the shell listed above with admin rights.
- Paste the whole command and press Enter. It downloads the agent, installs it, and enrolls the device using your token.
- Wait for it to finish without errors.
Step 4: Confirm the device checked in
Open RMM → All Devices or Hub → Endpoints → Devices. Within about a minute the device appears under its customer with a green Online badge. Hardware details, installed software, and performance data then fill in, and the monitoring policies for the device's customer or group apply automatically.
One token, many devices. Reuse the same token on every device for that customer until it hits its Max Uses or Expires date. You don't need a new token per device.
Deploy to many devices at once
For silent, unattended installs through Intune, Group Policy, an MDM, or your own scripts, download the package from the Installer ready window. On Windows and Linux, pass the token as THEONE_TOKEN:
# Windows (elevated)
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.rpmmacOS (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.
Replace <token> with your installer token. For a rollout bigger than 25 devices, set Max Uses high enough when you generate the token. Planning something large? Submit a ticket and we'll help.
Manage and revoke installer tokens
All your tokens are listed under Active Tokens, lower on the same Endpoints → Install page.
- Revoke: click Revoke next to a token, then confirm with Yes, Revoke. A revoked token can't add any more devices.
- Leaked or overshared? Revoke the token and generate a new one. You can do both yourself at any time.
- Finished a rollout? Revoke the token rather than waiting for it to expire.
Update the agent
Automatic (over-the-air) updates aren't available yet. To update a device, re-run the install command on it, using a current token from Endpoints → Install. The agent upgrades in place and the device keeps its existing record. If your old token has expired or been revoked, generate a new one first. If the device shows up twice afterward, submit a ticket.
Chromebooks
Chromebooks don't use this agent. They're managed in CMDB → Education and synced from the school's Google Admin console. See Education and Chromebook management in CMDB.
Troubleshooting
The device doesn't show up
- Give it two minutes for the first check-in.
- Make sure the command finished without errors and was run as an administrator.
- Check that no firewall or proxy is blocking outbound port 443.
- Check the token on Endpoints → Install under Active Tokens. If it's revoked, expired, or out of uses, generate a new one and run the command again.
- Restart the agent service on the device.
I cloned a virtual machine and now see a duplicate device
Clones share the original's hardware fingerprint. Delete the original device record, then let the clone enroll as a new device.