Skip to main content

Deploy the Defend agent

Updated

The Defend agent runs on each device you protect. It watches activity on the device, sends it to Defend, and carries out response actions you choose in the console, such as isolating the device or collecting forensics. Deploy the agent before anything else: Defend can't detect or respond on a device without it.

Before you start

  • You need administrator (or root) rights on the device.
  • Supported systems: Windows, macOS, and Linux.
  • The agent only makes outbound connections. You don't need to open any inbound firewall ports.
  • Your organization's license must include Defend. Which products the agent turns on comes from that license, not from the installer token.

Install the agent

Defend uses the same install page as RMM, CMDB, and Backups: Endpoints → Install. You can also start from Defend: go to Defend → Agents and click Install Agent (or Install your first agent if you have no devices yet).

  1. Go to Endpoints → Install.
  2. Click Generate Installer Token and pick the customer the device belongs to.
  3. Optional: set Max uses and Expires. If you leave them blank, the token works for 25 installs or 30 days, whichever comes first.
  4. Click Generate Token. In the Installer ready dialog, copy the token. It's shown only once.
  5. Choose the operating system and copy the install command, or download the package (.msi, .pkg, .deb, or .rpm).
  6. Run the command on the device as an administrator.
  7. Open Defend → Agents. The device appears as Protected within about a minute. This confirms the agent is enrolled; it doesn't confirm detections are being evaluated (see What is Defend?).

One token works for many devices. Reuse the same token across a customer's devices until it hits its install limit or expiry. To stop a token from adding more devices, click Revoke next to it under Active Tokens on Endpoints → Install, then generate a new one if you need it.

Deploy to many devices

Defend uses the same silent install as RMM. On Windows and Linux, pass the installer token as THEONE_TOKEN from Intune, Group Policy, an MDM, or your own scripts:

# 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 a Mac, Defend needs two approvals before endpoint detection and response (EDR) works:

  1. Endpoint Security system extension for the agent.
  2. Full Disk Access for The One Defend Endpoint Security.

The device shows EDR_DEGRADED until both are approved. On a Mac that isn't managed by an MDM, someone at the device has to allow each one. To avoid those prompts, pre-approve both through your MDM: a system extension policy and a Privacy Preferences (PPPC) Full Disk Access policy for team ID 44CSHFD6SS, bundle ID com.theonestack.agent.defendesf.

Replace <token> with the token from the Installer ready dialog. Need help planning a large rollout? Submit a ticket.

Tamper protection

Tamper protection watches for attempts to stop, change, or remove the agent. When it sees one, Defend raises a critical alert so you can respond. It detects and alerts on tampering; it doesn't block every attempt at the operating-system level.

To uninstall the agent on purpose, generate an uninstall token in the Defend console and use it with the uninstall command. Uninstall tokens are short-lived (about 4 hours), so generate one right before you remove the agent.

Troubleshooting

The device shows Offline even though it's running

  1. Check that the device has internet access and that a firewall or proxy isn't blocking outbound connections.
  2. Confirm the agent service is running on the device.
  3. If it keeps going offline, submit a ticket with the device name.

The installer token was rejected

The token may have been revoked, reached its Max uses, or passed its Expires date. Check Active Tokens on Endpoints → Install, and generate a new token if needed.

The agent won't uninstall

Tamper protection is on by default. Generate an uninstall token from the Defend console and include it with the uninstall command. Tokens expire after about 4 hours; if yours is older, generate a new one.

Common questions

Can I use the same token on multiple devices?

Yes. A token works for up to 25 installs over 30 days by default, or whatever limits you set when you created it.

Do I need a separate install for RMM and Defend?

No. One agent install covers the products your organization is licensed for.

Does the agent update itself?

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

What happens to a device's data after I remove it?

The device is removed from your device list. Events already collected stay in your event history until they age out after 90 days.

Related articles