KairosLink
Installing the macOS agent
How to install the agent on a Mac with a single command, which system permissions to grant, what the patching module does, and how to verify the device came online.
On macOS there is no build to wait for. The console gives you a command line, you paste it on the Mac, and the device is enrolled, same as on Linux.
This guide covers the installation, the system permissions macOS requires, what the patching module does on a Mac, and how to verify the device shows up online.
How it differs from the Windows agent
If you are coming from installing the agent on Windows, this is what changes:
| Windows | macOS | |
|---|---|---|
| What you get | An MSI file of about 17 MB | A command line, which fetches a .pkg |
| How it is produced | Per-customer build, 30 to 90 seconds | Already published, delivered instantly |
| Expiry | 7 days | Never expires |
| Customization at build time | Name, site, department, type | None |
| Architectures | 32 and 64 bit | Apple Silicon and Intel, in one universal binary |
| Hard requirement | Windows | System permissions granted by the user |
| Signing | Signed | Signed and notarized by Apple |
Getting the command
Under Customers, customer record, Devices tab, Installer card, Create Installer button. You need the device management permission.
In the modal, the macOS tab. That tab has no fields to fill in: it shows the command and nothing else. Copy command button.
The command looks like this:
curl -fsSL https://app.kairoslink.io/install/macos/TOKEN | sudo bash
The token travels in the URL, not inside a file. It is that customer's enrollment credential, the same one the Windows MSI and the Linux command use. Treat it like a password: whoever holds it can add devices to that customer.
The command does not expire. Unlike the MSI, which dies after 7 days, this line works as long as the customer's credential stays active. You can keep it in your internal documentation and reuse it.
Running the same line again updates the agent and does not duplicate the device in the console.
Requirements
Root. The sudo in the command is there for a reason: the agent installs as a system LaunchDaemon.
Apple Silicon or Intel. The binary is universal: the same download serves both architectures.
Outbound internet on 443 to the console. As on Windows and Linux, the agent initiates every connection outbound: no public IP and no inbound ports required.
The device does not need to reach GitHub. The console proxies and caches the agent files, so the download always comes from the KairosLink domain.
The package is signed, notarized and stapled, under the MITS GROUP LLC Developer ID. Gatekeeper lets it through without the user having to approve it by hand.
Installing without internet access
The same macOS tab in the modal offers the agent files for direct download. Leave them in the same folder on the Mac and run:
sudo ./install-macos.sh --token TOKEN --local
The installer verifies each file's SHA256 against the release SHA256SUMS before installing anything. A file that does not match is not installed.
What gets installed
There are two components, and the difference between them explains everything that follows:
| Path | What it is |
|---|---|
/Library/KairosLink/kairoslink-agent |
The binary |
/Library/KairosLink/KairosLinkSession.app |
The session agent |
/Library/KairosLink/uninstall-macos.sh |
The uninstaller |
/Library/LaunchDaemons/io.kairoslink.agent.plist |
The system daemon |
/Library/LaunchAgents/io.kairoslink.agent.session.plist |
The session agent |
/Library/Application Support/KairosLink/ |
Device identity |
/Library/Logs/KairosLink/ |
The logs |
The io.kairoslink.agent LaunchDaemon runs as root and does everything the console needs: enrollment, heartbeat, commands and inventory. It starts with the machine.
The io.kairoslink.agent.session LaunchAgent runs as each user, inside their graphical session. It is the only one that can talk to the macOS privacy permissions: a LaunchDaemon runs in the system domain, and macOS does not even consider it a candidate to request them.
That is why the agent is two pieces and not one. Without the session piece, the device is managed but the screen cannot be seen.
The system permissions
macOS requires the Mac's user to grant three permissions. There is no way to grant them remotely: macOS reserves that decision for whoever is sitting at the machine.
| Permission | What it is for |
|---|---|
| Screen Recording | Seeing the screen in remote control |
| Accessibility | Moving the mouse and typing in the remote session |
| Input Monitoring | Reading the keys the technician sends |
They are granted in System Settings, Privacy & Security, in each permission's section.
The session agent asks the user for any missing permissions. All three are granted on the device, and the state of each one is checked right there, in System Settings.
The permissions are tied to the agent's signature. As long as the agent is the signed and notarized one the console delivers, a user grants them once and they keep holding across updates.
Patching on a Mac
The patching module works the same as on Windows and Linux, through each system's native source. On macOS that is system updates through softwareupdate.
In the console it lives on the same Patching screen as the rest of the fleet:
- Survey of the device's pending updates
- Installation, selective or full, remotely, with live progress
- History of what was installed
- Reboot reported, schedulable and cancellable: no installation reboots the Mac without the technician's authorization
Approval, scheduling and reporting are the same as on the other two systems: there is no separate screen for Macs.
Verifying it worked
In the console, the Devices screen. Find the device and look at the Last seen column: that is what confirms it is actually alive and not just registered. The device shows up in under a minute and accepts commands and inventory from then on.
As on Windows and Linux, the row existing is not enough: what confirms the agent is talking to the console is the last connection.
On the Mac, the state of both components:
sudo launchctl print system/io.kairoslink.agent
launchctl print gui/$(id -u)/io.kairoslink.agent.session
Logs live in /Library/Logs/KairosLink/.
When the device does not show up
The command returned an error and installed nothing. The installer is explicit: it says if root is missing, if it could not download a file, or if a SHA256 does not match. Read the message.
The installer said OK and the device does not show up. The causes are the same as on Windows and Linux: the token was rotated, the customer was deleted, the plan's device cap was reached, or the Mac has no route to the console on 443.
The device shows up but remote control does not open. Check the three permissions on the Mac, under System Settings, Privacy & Security. If any is missing, the device's user has to grant it.
Reinstalling
Reinstalling over an existing installation does not duplicate the device: it is recognized by its hardware fingerprint, and the state directory also preserves its identity.
To update the agent, run the same install command again. Do not use the customer's Agents tab: that screen works with the Windows installer.
Uninstalling
On the Mac:
sudo /Library/KairosLink/uninstall-macos.sh
On the console side, the device behaves as it does on Windows: if the agent manages to report in, it disappears from the list; if not, it stays Offline and you remove it with Remove from list.
Frequently asked questions
Do I need to generate anything before installing? No. The command already exists, you copy it and paste it.
Does one customer's command work for another? No. It carries that customer's enrollment credential inside.
Does it work on Apple Silicon and Intel? Yes. It is a universal binary: the same download covers both.
Will Gatekeeper block the installation? No. The package is signed, notarized and stapled, under the MITS GROUP LLC Developer ID.
Can I grant the system permissions remotely? No. macOS reserves that decision for the device's user. The session agent asks for them on the Mac.
What patches a Mac?
System updates through softwareupdate, from the same Patching screen as the rest of the fleet.
Does reinstalling duplicate the device in the console? No. Run the same line again: it updates the agent and the device stays the same one.
Updated September 6, 2026