macOS agent
Install PulseHA on Apple Silicon and authenticate in a browser.
On macOS the agent ships as a notarised .pkg that installs a background daemon and the PulseHA desktop app. You sign in from the app, not from a terminal. Use this page to install, authenticate and confirm the device is connected.
Before you start#
- A Mac on Apple Silicon or Intel. There is a separate package for each.
- Administrator rights on the Mac to run the installer.
- A Console account with the owner, admin or user role, so you can approve the device. Adding a device needs the
devices.createpermission. - A browser you can sign in to the Console with. Required SSO applies to that browser session.
- You may authorise up to 5 devices per organisation. Re-authorising a Mac you already own does not count.
macOS does not provide pulsectl. Ignore any Linux CLI instructions when working on a Mac.
Install#
- Open Network → Devices → Add Device in the Console.
- Under 1 Select Platform, choose macOS. The Install Agent text reads: notarised
.pkginstallers for Apple Silicon (arm64) and Intel (amd64). - Choose Download for macOS (Apple Silicon) or Download for macOS (Intel). The same files are on Downloads as
pulseha-agent-arm64.pkgandpulseha-agent-amd64.pkg. - Open the downloaded
.pkgand follow the installer.
The installer loads a LaunchDaemon (com.pulseha.agentd), creates a pulseha group and adds the console user to it so the app can talk to the daemon over its local socket.

Add Device with macOS selected: two package downloads, then the note to sign in from the app.
Sign in#
- Open PulseHA from Applications or Spotlight.
- The window shows Sign in to PulseHA and the note that you will be redirected to your browser.
- Choose Continue in Browser.
- The browser opens the Console’s Authorize Device page with the code already in the URL. Sign in if asked.
- Once you are signed in, the page approves the code and shows Device authorized. Return to your client to finish. Choose View devices or return to the app.
If the browser lands on Authorize Device without a code, paste the code into Device Code and choose Authorize Device. Codes are single-use and expire 15 minutes after the app requests them.
What you should see#
In Network → Devices the Mac appears with its hostname and your email beneath it. The Connection chip reads Pending until the daemon registers, then Online. The list refreshes itself every 30 seconds.

The device drawer for a Mac. Connection, Version and Tunnel IP confirm that the daemon registered.
| Chip | Meaning |
|---|---|
| Pending | Approved in the browser, daemon not yet registered |
| Online | Heartbeat received within the last 4 minutes |
| Tunnel down | Daemon is alive but reports the tunnel disconnected |
| Recently seen | Last heartbeat between 4 and 10 minutes ago |
| Offline or Never connected | No recent heartbeat, or none ever |
The Posture column shows Compliant, Non-compliant, Stale or Unknown. Stale means the last check is too old to trust; it is never shown as compliant.
Access stays default-deny until an Allow policy includes your user, group or this device and names at least one service. See Your first access policy.
Troubleshooting#
- Nothing happens after Continue in Browser. Check that a browser window opened and that you completed sign-in there. Return to the app and choose Continue in Browser again; a new code is issued.
- The browser shows invalid or expired device code. The 15-minute window passed, or the code was already used. Request a new one from the app.
- The browser shows a device-limit message. You have 5 devices in this organisation. Ask an owner or admin to revoke one you no longer use.
- The browser signed in to the wrong organisation. The device is bound to the organisation of the signed-in Console session. Sign out of the Console, sign in with the right account, then retry from the app.
- The row stays Pending. The approval succeeded but the daemon has not registered. Quit and reopen PulseHA. If it persists, confirm the Mac has outbound HTTPS.
- Online but the app does not connect to a service. Check whether the device is Blocked, Archived or Revoked in the device drawer, whether an enforcing posture policy marks it Non-compliant, and whether an Allow policy covers it. Policy simulation shows which policy decides.
- The device was revoked. Signing in again from the same Mac with the same account re-authorises the existing record instead of creating a new one.