Install the agent on a Mac, in person
A step-by-step install and test checklist for a technician standing at a Mac. Tick each step as you go. Nothing is saved.
Applies to Technician Admin
Use this page when you are at a Mac with the customer's agent to install. We do not roll out Macs remotely. You install, grant each permission, and run the tests before you leave.
The agent is 1.1.186 or later. The installer is one package. It puts TheOneAgent.app in Applications, the Defend sensor (a macOS system extension), a menu-bar app, and a first-run window on the Mac.
What the install does#
| Piece | What it is | Prompt you will see |
|---|---|---|
| TheOneAgent.app | The agent. Runs as a background service and stays alive as the one name macOS shows in every privacy list. | Three privacy switches, all named TheOneAgent |
| Defend sensor (system extension) | Watches process and file activity for Defend. Installed with every Mac, even if Defend is off for the customer. | System Extension Blocked, then Allow in System Settings |
| Menu-bar app | Shows agent status and a Fix permissions... button. | None |
| First-run window (TheOneAgentOnboarding) | Opens only when you double-click the package with no token. Enrolls the Mac and walks the permissions. | None |
| Edge network extension | Staged only. Off. Not part of this install. | None expected. Do not approve one. |
Get ready#
Install the package#
Choose one way. The Terminal way is the default, because it enrolls the Mac with no typing of the token.
Terminal way (default). Open Terminal, paste the macOS block from Generate Token, press Return, and type the administrator password when asked. The block has this shape. Always copy it from the page. Never type a token by hand.
curl -fsSL "<installer URL>" -o /tmp/TheOneAgent.pkg && printf '%s' '<TOKEN>' | sudo sh -c 'umask 077; cat > /var/root/theoneagent-enrollment.token' && sudo installer -pkg /tmp/TheOneAgent.pkg -target /
Double-click way (use when Terminal is not allowed). On Downloads, choose the macOS installer. Open the package and follow the Installer steps. When it finishes, the first-run window The One Agent opens. Step 1 is Enroll device: paste the enrollment token, choose Verify, then Install & Enroll. Step 2 is Permissions. Step 3 is Monitored.
On the Terminal way the first-run window does not open, because the Mac already has its token. You grant the permissions from the menu-bar app instead. The next section covers both.
Approve the Defend system extension#
The package asks macOS to load the Defend sensor as soon as it installs. If someone is signed in, the prompt appears right away. If no one is, it appears at the next sign-in.
sudo /Applications/TheOneAgent.app/Contents/MacOS/TheOneAgentHost ext activate com.theonestack.agent.defendesf --timeout 30
Grant the three privacy permissions#
Every privacy list shows one entry for the agent, named TheOneAgent. You switch it on in three lists. Use the first-run window if it is open (it turns each row green only when macOS says the permission is on), or the menu-bar panel, Permissions, Fix permissions.... Each Open Settings button opens the right list for you, and macOS may ask for the administrator password.
Full Disk Access
Lets the agent read files across the disk, for backup, inventory, and scripts that read user folders. macOS never shows a prompt for this one. You switch it on by hand.
Screen Recording
Lets you see the screen during a Connect session. On macOS 15 and later the list is named Screen & System Audio Recording.
Accessibility
Lets you click and type during a Connect session. Without it you can see the screen but not control it.
Notifications
The agent can show a banner for a permission or restart alert. If macOS asks "Allow Notifications?" or asks about TheOneAgent notifications:
If a VPN prompt appears
macOS may say that TheOneAgent would like to add VPN configurations. That is the Edge network extension. Edge is off for customers.
Run the tests#
Do these at the Mac, in order, before you leave. If a test fails, use the troubleshooting section below, then run the test again.
If a test fails#
The Mac never appears in All Devices
- The command stopped with an error. Read the last line. A message that the token is not the minted shape means the token was cut off. Mint a new one. Never reuse a failed command.
- The package installed and the row is missing after 5 minutes. The token may be revoked, expired, or for another customer. Check Active Tokens. The Mac must reach the internet. Then see When a device will not check in.
- The first-run window says "Enrollment was not accepted". The token was wrong or used up. Choose Use a different token.
- The first-run window says "Enrolled, not online". The Mac has a device id but has not checked in yet. Wait for the first check-in, then refresh the device list.
What you see when a permission is missing
| Permission | What you see | Fix |
|---|---|---|
| Full Disk Access | Mac permissions needed: Full Disk Access on the device page. The first-run window row is not green. Backup, inventory, and scripts that read user folders come back empty or fail. | Switch TheOneAgent on under Privacy & Security, Full Disk Access. There is no prompt for this one. Wait 30 seconds. If the banner stays, switch it off and on again. |
| Screen Recording | The Connect session ends with endpoint needs permission: Screen Recording, or the device says the device needs to grant permission. The Mac may open the Screen Recording list by itself. | Switch TheOneAgent on under Screen Recording (Screen & System Audio Recording on macOS 15 and later). On macOS 15 and later, choose Allow if macOS asks again. |
| Accessibility | You see the screen but the pointer and keys do nothing. The viewer says remote control needs Accessibility permission. | Switch TheOneAgent on under Accessibility. Remote control also needs a person signed in at the Mac. If nobody is signed in, the session is view-only. |
| System extension (Defend sensor) | System Extension Blocked appeared and was dismissed, or systemextensionsctl says activated waiting for user, or the first-run window row System Extension is not green. | Open System Settings, Privacy & Security, choose Allow under the blocked-software message. If it is not there, run the ext activate line above, then try again. If macOS asks for a restart, restart, sign in, and run the test again. |
| Notifications | No banner for agent alerts. | System Settings, Notifications, TheOneAgent, Allow Notifications. |
Other problems
- Connect shows a black or blank screen. Screen Recording is off or was reset. Fix it above, then start a new session.
- Connect works but you cannot control the Mac. Accessibility is off, or nobody is signed in at the Mac. Fix it above.
- No Connect session before anyone has signed in. The login window cannot be shared. Sign in once, then connect. Or use Open Terminal on the device.
- The device page shows the wrong agent. Wait for the next check-in. A restarted Mac runs the new agent after the first check-in.
- Two rows for one Mac. Do not delete either one. Write both down and ask engineering.
- The agent runs under an older identity. If engineering sees an identity of legacy-node, the app could not run at install. Run the installer again. Until then macOS shows the permissions under the old name.
Screens by macOS version#
The steps are the same on every supported Mac. Names and places move.
- macOS 13 and later. Settings is named System Settings. Background agents and extensions are under General, Login Items & Extensions.
- macOS 15 and later. Screen Recording is named Screen & System Audio Recording, and macOS re-asks about it from time to time.
- macOS 11 and 12. The settings app is named System Preferences, and the lists are under Security & Privacy, Privacy. The menu names are the same: Full Disk Access, Screen Recording, Accessibility.
Managed Macs#
A Mac managed by an MDM that has user-approved enrollment can have most prompts removed before you arrive. The deployment profile pre-approves the Defend sensor, pre-grants Full Disk Access and Accessibility, and lets a standard user switch on Screen Recording. Screen Recording can never be pre-granted. Every Mac needs that one click. If the prompts still appear, the profile did not apply. Check the profile reached the Mac before the package did. You still run every test above.
What's next#
Was this article helpful?