Enroll a device

Before you start

• This is an IT task. It assumes you can install software on the computer with administrator rights and, on Linux and Windows, paste a command into a terminal window. If you do not look after your company’s computers yourself, do this together with the person who does.
• You can manage devices in Zonitix. If buttons on the device screens are greyed out, ask an admin for device management rights.
• Admin rights on the machine you are enrolling: the Mac login password, root on Linux, or a local administrator on Windows.
• A supported system: macOS 13 or later, a 64-bit Linux distribution that uses systemd, or 64-bit Windows.
• To email the Mac installer to staff, your mail server must be connected first. See Set up email.

Get the agent ready (once per platform)

1. 1

   Step 1: Open device settings

   In the sidebar, go to DevicesSettings. You can also search for “Enroll devices”.

   Pick the platform card at the top: “macOS”, “Linux” or “Windows”. The “Enrollment” section opens with a short setup checklist.

2. 2

   Step 2: Adopt the agent

   Under “Install the agent”, click the adopt button, for example “Adopt macOS agent v1.2.3” (the version number will differ). Zonitix checks the agent’s signature and checksum, then hosts it on your own instance.

   You only do this once per platform. The install options for that platform appear straight after.

Install on a Mac

1. 3

   Step 3: Get the installer

   In the “Enrollment” section, click “Download ZonitixAgent.pkg”.

   To let staff install it themselves, open DevicesInventory, click “Add devices”, choose “macOS”, pick people under “Email install to users”, then click “Send install email”.

2. 4

   Step 4: Run it on the Mac

   Open ZonitixAgent.pkg and follow the installer. When macOS asks, enter the Mac’s login password.

3. 5

   Step 5: Check the menu bar

   A small shield icon appears in the Mac’s menu bar, and the agent runs in the background from then on.

   The Mac reports to your instance once the agent has your instance’s address and enrollment token. They reach a Mac in one of two ways: in a package built for your instance, or in the agent’s configuration profile sent by device management.

Install on Linux

1. 6

   Step 6: Copy the install command

   On the “Linux” card, the “Enrollment” section shows a one-line command with a copy button. It already points at your instance’s API address (your instance name followed by -api), and the script it downloads carries your enrollment token. It looks like this:

   curl -fsSL https://<your-instance>-api.zonitix.com/agent/linux/install | sudo bash

2. 7

   Step 7: Run it on each machine

   Paste it into a terminal on the machine and run it as root. It installs the agent as a background service and enrolls the machine. After that the agent updates itself when you adopt a newer build. To roll it out widely, add the same line to your usual setup tool.

Install on Windows

1. 8

   Step 8: Copy the install command

   On the “Windows” card, the “Enrollment” section shows a one-line PowerShell command with a copy button. It looks like this:

   irm https://<your-instance>-api.zonitix.com/agent/windows/install | iex

2. 9

   Step 9: Run it as administrator

   On the PC, right-click PowerShell and choose Run as administrator, then paste the command. It installs the ZonitixAgent service and a system-tray app, then enrolls the PC.

   The screen notes the agent can also be rolled out as an MSI through Intune, Group Policy or SCCM.

Approve the new device

1. 10

   Step 10: Find it in Inventory

   Go to DevicesInventory. A new machine appears after its first check-in, marked “Pending approval”.

2. 11

   Step 11: Approve it

   Click “Approve” on the row. Until you do, the device is not trusted and does not count toward compliance. This stops someone enrolling a machine you don’t know about.

   Then open the device and assign its owner. Zonitix does not set the owner from whoever is signed in to the machine.

3. 12

   Step 12: If it is a new hire’s computer, link it

   When onboarding lists a laptop or desktop for a new hire, Zonitix reserves a place for it. Inventory then shows a banner such as “2 computers are reserved for new hires — they become managed devices when they enroll.”

   If the serial number was recorded on the onboarding hardware step, the machine is linked to the new hire on its own when it enrolls. A Linux machine reports a machine ID in place of the maker’s serial number, so the number on its label will not match. If there is no match, Inventory asks, for example, “MacBook Pro just enrolled — is it Jane Doe’s laptop?” Click “Yes, link it” to make the new hire its owner, or “Not a new hire’s” to stop being asked about that machine.

What you should see

If something goes wrong

The Enrollment section says no agent is available from the store yet

There is no signed agent for that platform to adopt yet. You cannot fix this from your side. Contact Zonitix support.

A Mac shows the shield icon but never appears in Inventory

Check that the Mac is online. If it is, the agent may not have been given your instance’s address and enrollment token, and it waits until it has them. Installing the same package again will not change that. Contact Zonitix support.

The Linux or Windows command says the agent "is not configured on this tenant yet"

The agent for that platform has not been adopted. Do step 2 of "Get the agent ready", then run the command again.

The command stops with "run as root" or "Run this in an elevated PowerShell"

Run it again with sudo on Linux, or from a PowerShell window opened with Run as administrator on Windows.

A rebuilt or reused machine will not enroll

Open the device in Inventory. If it was retired, click "Return to service". If it was wiped and reinstalled, click "Allow re-enrollment", then install the agent again.

You need to remove the agent from a machine that is offline or leaving the company

The usual way is the "Uninstall agent" button under Manage on the device, but that needs the machine to check in. Otherwise go to Devices → Settings, pick the platform and open the "Uninstall" section: the "Uninstall the agent" card gives a command to copy and run on the machine itself (an admin password on a Mac, sudo on Linux, an administrator PowerShell on Windows). On a Mac that is also in Apple MDM, remove the enrollment profile separately in System Settings → General → VPN & Device Management. Then retire the device in Inventory.

The enrollment token may have leaked

In Devices → Settings, in the Enrollment section, click "Rotate tenant enrollment token" and confirm with "Rotate token". This revokes the current token for every platform. Devices already enrolled are not affected. The one-line Linux and Windows commands keep working, because they download a fresh script each time. An install script you saved or pushed through another tool earlier carries the old token and can no longer enroll new devices, so fetch it again.

Sending the install email fails with "SMTP isn’t configured"

Connect your mail server first (see Set up email), or download the .pkg and share it yourself.

Still stuck? See When something goes wrong, or Contact Zonitix support.

Where next

• Manage a device day to day
• Group devices
• Push a compliance profile
• Onboard your first hire
• Set up email
• Offboard someone
• See what software is installed
• Install the Zonitix Agent on your Mac (for the employee who gets the email)