Skip to content →
Log in

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.create permission.
  • 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#

  1. Open Network → Devices → Add Device in the Console.
  2. Under 1 Select Platform, choose macOS. The Install Agent text reads: notarised .pkg installers for Apple Silicon (arm64) and Intel (amd64).
  3. Choose Download for macOS (Apple Silicon) or Download for macOS (Intel). The same files are on Downloads as pulseha-agent-arm64.pkg and pulseha-agent-amd64.pkg.
  4. Open the downloaded .pkg and 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.

Install Agent and Authenticate sections of Add Device with macOS selected

Add Device with macOS selected: two package downloads, then the note to sign in from the app.

Sign in#

  1. Open PulseHA from Applications or Spotlight.
  2. The window shows Sign in to PulseHA and the note that you will be redirected to your browser.
  3. Choose Continue in Browser.
  4. The browser opens the Console’s Authorize Device page with the code already in the URL. Sign in if asked.
  5. 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.

Device drawer for a Mac showing Connection, Platform, Version and Tunnel IP

The device drawer for a Mac. Connection, Version and Tunnel IP confirm that the daemon registered.

ChipMeaning
PendingApproved in the browser, daemon not yet registered
OnlineHeartbeat received within the last 4 minutes
Tunnel downDaemon is alive but reports the tunnel disconnected
Recently seenLast heartbeat between 4 and 10 minutes ago
Offline or Never connectedNo 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.