Skip to main content
Version: 11.5.0

Endpoint Guard for macOS

Endpoint Guard for macOS reports AI tool activity and applies your Managed Desktop Tools configuration. It also connects managed Claude Code and Codex sessions to supervisors. It runs in the signed-in user's session, so it can safely merge settings in that user's home folder.

On the Mac, Endpoint Guard installs as AgentPass. The application is AgentPass.app, and its components appear under that name in System Settings.

Before You Begin​

You need:

  • macOS 13 or later
  • Outbound HTTPS from the Mac to your organization's gateway address. Endpoint Guard opens no listening ports
  • An enrollment token from the AgentPass console

A Mac with a Secure Enclave keeps its workstation signing key there. Other Macs keep the key in the keychain, bound to that Mac.

Install Endpoint Guard​

Choose the installation method that matches your deployment:

  • Endpoint Guard installer package. The installer asks for the gateway address and enrollment token, and configures the user who installs it. Your device-management tooling can run it with no user interface.
  • HYPR Passwordless for Mac package. The installer carries Endpoint Guard and registers it to start at login.
  • AgentPass disk image. Open the disk image, and drag AgentPass onto the Applications folder beside it. Then open AgentPass from /Applications, configure enrollment and complete the setup approvals.

Endpoint Guard runs from /Applications only. Open it from there, not from the disk image or your Downloads folder.

Install on One Mac​

Download the installer package from Desktops → Installation in the console, which offers a download for each platform your gateway has installers for. The download is a zip that holds the installer. When the tab reads Installers aren’t available right now, get the package from your HYPR representative. It is named for its version, such as AgentPass-<version>.pkg, and its window is titled Endpoint Guard for macOS. Whoever installs needs an administrator's name and password, the gateway address and the enrollment token.

  1. Double-click the installer package. It opens at the Configuration step.
  2. In AgentPass server, enter the gateway address. It starts with https://.
  3. In Enrollment token, paste the token. It starts with ssf_.
  4. Select I agree to the End User License Agreement, and click Continue.
  5. Click Install, and enter an administrator's name and password when macOS asks.

When it finishes, the installer writes the gateway address and token to the user's configuration file, and opens AgentPass. The AgentPass Setup window then asks for the macOS approvals.

The installer does not check the token

The installer checks only that the gateway address starts with https://, and that the token looks like an enrollment token. It does not contact the gateway. A Mac with a mistyped or removed token installs normally, then keeps trying to enroll and never appears in the console. Confirm every Mac afterwards. See Confirm the Installation.

Install From a Deployment Tool​

To install with no user interface, from your device-management tooling or from Terminal, place a config.json file with the enrollment details beside the installer package. The file has the same contents as the user's configuration file, and needs both the gateway address and the token.

sudo installer -pkg AgentPass-<version>.pkg -target /

The installer copies the file into the signed-in user's ~/.hypr folder, and opens AgentPass in that user's session. It uses the file only if the file and every folder above it belong to root or to the signed-in user, and no other user can change them. A device-management staging folder, or the user's own Downloads folder, qualifies. Otherwise, the installer ignores the file, and says so in the installation log, /var/log/install.log.

Without a config.json beside the package, the installer leaves an existing configuration file as it is. If no user is signed in, there is no user to configure, so provision the configuration file separately.

Protect the enrollment token

The token is in the config.json file you deploy, so treat the deployment like a credential. Limit who can read it, and do not reuse a token outside the intended organization. If a token is exposed, remove it in the console and create a new one. Workstations that already enrolled keep reporting.

Update Endpoint Guard​

Endpoint Guard updates itself from your gateway. It checks every hour, and installs a newer version once your gateway offers one.

  • It downloads the update only from your gateway.
  • Before it installs, it confirms that the installer is signed by HYPR and notarized by Apple, and that the version is newer than the one installed.
  • The update runs in the background, and needs no administrator password. The network filter is replaced with the app, and macOS does not ask you to allow it again.
  • It waits while an Endpoint Guard prompt is on the screen.

ap-cli status shows the last check, and what it found, under Updates.

You can still install a newer version yourself, by hand or through your device-management tooling.

To update an installation from the installer package, run the newer installer package. It stops the running AgentPass and replaces it. On a configured Mac, AgentPass server shows the current gateway address, and leaving Enrollment token empty keeps the current token. Select I agree to the End User License Agreement again to continue. The workstation keeps its enrollment.

To update a disk-image installation:

  1. In the disk image window, open Quit AgentPass. The running components stop.
  2. Drag AgentPass onto Applications, and choose Replace.

The network filter keeps working throughout an update.

Configure Enrollment​

The installer package writes this file for the user who installs Endpoint Guard. For a disk-image installation, write the gateway address and enrollment token to the signed-in user's configuration file. Your device-management tooling can provision this file before or after Endpoint Guard starts.

~/.hypr/config.json
{
"gatewayBaseURL": "https://<your-gateway-url>",
"ssfEnrollmentToken": "<enrollment token>"
}

Restrict the file to the user with mode 600. Alternatively, place the token in ~/.hypr/ssf-enrollment-token. If both carry a token, the token in ~/.hypr/ssf-enrollment-token is used. The installer package removes that file, so the token you enter in the installer is the one in force.

Endpoint Guard reads the configuration file every 30 seconds, so nothing needs restarting after you change it. It checks for a newly delivered token every five minutes. Without an https:// gateway address, the Mac contacts no gateway, and the AgentPass menu shows Not set up — ask your administrator.

Changing the gateway address enrolls the Mac at the new gateway as a new device, which needs an enrollment token from that gateway. The old device stays listed in the old gateway's console.

After enrollment, the workstation authenticates with its signing key and keeps its identity across restarts. Keep an active enrollment token available through your device-management tooling, so the workstation can re-enroll after a capability update. If you remove the token a deployment uses, deliver a replacement token to those workstations.

Approve the macOS Components​

The installer package opens the AgentPass Setup window when it finishes. After a disk-image installation, the window opens when you first open AgentPass from /Applications. To open it again later, choose Run Setup… from the AgentPass menu.

  1. In the AgentPass Setup window, click Run Setup.
  2. Approve each macOS prompt. The setup window confirms each component as it becomes ready.

The setup window lists these components.

Setup windowPurposeApproval
Network extensionRuns the Endpoint Guard network extensionAllow the system extension when macOS asks
Traffic filterAttributes network connections and enforces configured egress controlsAllow AgentPass to filter network content
AgentPass serviceEnrolls the Mac, discovers AI tools and applies managed configuration. Restarts automatically if it stopsNone
Opens at loginOpens the AgentPass menu bar app at loginNone
Full Disk AccessOptional. Lets the network extension's Endpoint Security client report each AI tool the moment it starts or exitsTurn on the AgentPass extension under Privacy & Security → Full Disk Access, or grant it from your MDM
The AgentPass Setup window showing the network extension, traffic filter, AgentPass service and opens-at-login components ready

Full Disk Access is optional. With it, Endpoint Guard sees each AI tool start and exit as it happens. Without it, Endpoint Guard looks for AI tools every 15 seconds, which can miss one that runs for less than that. Nothing else depends on it, and Setup never waits for it. The Full Disk Access row appears once the network extension runs. Open Full Disk Access opens the list, where the extension appears as soon as it has asked. Turned on later, it is used within a minute, without a restart. The entry to turn on is the extension, com.hypr.HyprPasswordless.AgentPass.systemextension. An AgentPass entry in the same list is the menu bar app, which does not need it. ap-cli status says which of the two ways is in use.

Endpoint Guard asks for no notification permission.

Approve From Your MDM​

On a Mac you manage, grant the approvals from your MDM, so the user sees no prompt for them. Both payloads must come from the MDM the Mac is enrolled in. A profile installed by hand cannot grant either.

ApprovalPayloadSettings
The system extensionSystem Extensions (com.apple.system-extension-policy)AllowedSystemExtensions: team 85XQ42NB2J, com.hypr.HyprPasswordless.AgentPass. A policy that also limits AllowedSystemExtensionTypes must allow both NetworkExtension and EndpointSecurityExtension for the team
Full Disk AccessPrivacy Preferences Policy Control (com.apple.TCC.configuration-profile-policy)SystemPolicyAllFiles, with Identifier com.hypr.HyprPasswordless.AgentPass, IdentifierType bundleID, Authorization Allow, and the code requirement below
identifier "com.hypr.HyprPasswordless.AgentPass" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] and certificate leaf[field.1.2.840.113635.100.6.1.13] and certificate leaf[subject.OU] = "85XQ42NB2J"

Without the Full Disk Access payload, a managed Mac works as one whose user has not turned it on.

The AgentPass icon in the menu bar confirms the user interface is running. Its menu offers About AgentPass, Run Setup… and Share Diagnostics…. About AgentPass opens a window with the AgentPass and network filter versions, the gateway and the device ID. Copy Details copies them for a support request. Hold ⌥ (Option) while the menu is open to add Share Logs… and Trace…, as macOS does for its own menu bar items. Share Diagnostics… saves the ap-cli status report, and Share Logs… saves the last two hours of Endpoint Guard logs, each as a text file to attach to a support request. Neither file holds tokens or keys. When something needs attention, the icon carries a badge, and the menu lists the problem at the top, with what AgentPass does next. See Troubleshoot a Mac. You manage everything else from the AgentPass console.

The macOS menu bar with the AgentPass icon

Confirm the Installation​

Confirm the installed components in System Settings:

  • Network → Filters lists HYPR AgentPass as an enabled content filter.

    macOS System Settings showing HYPR AgentPass as an enabled content filter
  • General → Login Items & Extensions lists AgentPass under Open at Login and App Background Activity.

    macOS System Settings showing AgentPass under Open at Login and App Background Activity
  • General → Login Items & Extensions lists the AgentPass extension under Endpoint Security Extensions. It is the network extension, which also watches for AI tools starting, so macOS files it there and not under Network Extensions.

    macOS System Settings listing the AgentPass network extension

After enrollment, the Mac is counted under its enrollment token on Desktops → Installation. See Review and Revoke Desktops. It is also listed on the By desktop tab of Activity → Desktop activity, with the matching tool activity it sends. See Desktop Activity.

Check a Workstation with ap-cli​

Endpoint Guard includes ap-cli, a command-line tool that reports the state of a workstation. Its reporting commands only read state. They are safe to run on any Mac, including from a device-management check script.

/Applications/AgentPass.app/Contents/Helpers/ap-cli status

ap-cli status exits with 0 when the workstation is healthy, and 2 when it finds a problem. It ends with findings that explain each problem. The report has these sections.

SectionWhat it answers
AgentPassWhich version is installed, and whether the network extension is active with a filter configuration that belongs to Endpoint Guard
GatewayWhich gateway address is in force and where it came from, whether the gateway answers, and whether an enrollment token is present
EnrollmentWhether the workstation is enrolled, and which version of the managed configuration it applied
Network filterWhether the filter is enforcing or observing, and what it does when the gateway is unreachable. Also the hosts blocked for each tool, with the code-signing identities each block is scoped to
AgentsFor each AI tool: whether it is installed and signed in, whether its inference is routed through the gateway, whether its egress is enforced, and which MCP servers its configuration carries

ap-cli has these other commands.

CommandPurpose
ap-cli status --jsonThe same report as JSON, to attach to a support request or read from a script
ap-cli versionThe installed and active versions of the application and the network extension
sudo ap-cli logs brain --last 2hRecent log entries from the service that applies managed configuration
ap-cli reenrollEnrolls a revoked workstation again, as a new device. See When a Workstation Is Revoked
ap-cli traceWhat Endpoint Guard recorded of what it did and why. See Trace What AgentPass Did

Run the copy of ap-cli inside AgentPass.app. The service answers only that copy.

Trace What AgentPass Did​

The trace answers why AgentPass did something. Each Endpoint Guard component records what it did and decided, on this Mac only, with credentials redacted.

ComponentWhat it records
The service that applies managed configurationIts calls to the gateway, the AI tools it saw start and stop, its channels' runs and updates, and its state as ap-cli status shows it
The network filterIts blocks, the connections it refused unread, the AI tools Endpoint Security saw start and exit, and its policy
The menu bar appWhen the Mac slept, woke, locked, turned its display off or ran its screensaver, so a gap in the trace explains itself
Every componentIts log lines, and its health: what is wrong, and when it was found and resolved

The service's and the menu bar app's traces are in ~/.hypr/trace. The network filter's is in /Library/Application Support/HYPR/AgentPass/Trace, readable by administrators only.

The flight recorder always keeps the last 30 minutes. To keep more while you reproduce a problem, start a full trace. It also records the programs AI tools start, for up to a day:

sudo /Applications/AgentPass.app/Contents/Helpers/ap-cli trace start --for 30m

--for takes a length such as 90s, 30m or 2h. What a full trace records is kept for a day after it ends. sudo ap-cli trace stop ends it early.

Read the Trace​

Hold ⌥ (Option) while the AgentPass menu is open, and choose Trace….

  • The strip at the top says whether AgentPass is healthy, or how many problems it has. It shows how the service, the network filter, Endpoint Security, the gateway, the enrollment, the profile and manifest, and the Claude and Codex channels are. A channel shows starting with its version until the gateway gives it a session, then running. Click one to see the event that last changed it.
  • The timeline shows each component on its own line. A problem is a band from when it was found until it was resolved. The timeline is shaded while the Mac was asleep, locked, had its display off or ran its screensaver.
  • Click an event to see what it means, what AgentPass did about it, what you can do, and what was recorded just before and after it. Click the timeline to see each component's state at that moment.
  • Problems shows only what went wrong. Live follows new events as they are recorded.
  • Full trace copies the commands that start and stop a full trace, to run in Terminal.

On a Mac where the user is not an administrator, the network filter's trace cannot be read, and the window says so.

Send a Trace​

ap-cli trace export writes this Mac's traces to one .aptrace folder. It holds no tokens or keys. Zip it, and attach it to a support request:

/Applications/AgentPass.app/Contents/Helpers/ap-cli trace export --out ~/Desktop

In the Trace window, Trace → Export… does the same, and Trace → Open Exported Trace… opens one sent to you. ap-cli trace status says what each component's trace holds.

Pause Enforcement on One Workstation​

Quitting the AgentPass menu bar app does not stop Endpoint Guard. The service and the network filter keep running. To stop enforcing egress on one workstation, use either:

  • Block direct traffic on this desktop, in the Mac's own settings in the console. See Change One Desktop's Settings. Its tools stay routed and provisioned, and the change takes effect on its next check-in.
  • System Settings → Network → Filters on the Mac. Turning off HYPR AgentPass stops all filtering until you turn it back on.

When the Gateway Is Unreachable​

A managed workstation checks every 30 seconds that it can reach the gateway. While it cannot, it applies your organization's outage behavior:

  • Stop traffic. Nothing changes. The tools stay routed through the gateway, and their egress blocks stay in place, so routed tools do not work until the gateway answers.
  • Let traffic through. Nothing changes for the first 15 minutes, so a short interruption releases nothing. Then the workstation lifts its egress blocks, and withdraws each tool's routing, so the tools reach their providers directly. MCP servers and Cursor hooks stay in place, except Claude Desktop's MCP servers, which are part of its gateway configuration. When the gateway answers again, the workstation routes the tools again, and then restores the blocks.

A desktop's own settings in the console name these choices Fail closed and Fail open.

A workstation that starts while it cannot reach the gateway, for example away from your network, applies the configuration it last received. A tool that is already running keeps its routing until it restarts. In ap-cli status, the outage row of the Network filter section shows when an outage started, and when the blocks lift or lifted. The AgentPass menu says the same, such as Lifts its blocks at a given time if the gateway still does not answer.

When a Workstation Is Revoked​

When you revoke a desktop, Endpoint Guard stops managing it at its next check-in, as when you turn off Configure agents on this desktop. It removes its egress blocks, restores each tool's routing, MCP servers and hooks, and shows the user a notice. A workstation that was offline when you revoked it does this when it next reaches the gateway.

The gateway never accepts a revoked identity again. To bring the workstation back, make sure it has an active enrollment token, and run this command as the signed-in user:

/Applications/AgentPass.app/Contents/Helpers/ap-cli reenroll

ap-cli reenroll discards the revoked identity, and enrolls the workstation as a new device. The revoked device stays listed as Revoked.

What Endpoint Guard Changes​

Before its first change to a tool, Endpoint Guard backs up the tool's original settings. It then merges managed settings with the developer's own configuration. It writes to these locations.

ConfigurationLocation
Claude Code routingANTHROPIC_BASE_URL in the user's login session or an existing enterprise managed-settings.json file
Codex routingopenai_base_url in ~/.codex/config.toml, and in ~/Library/Developer/Xcode/CodingAssistant/codex/config.toml for the Codex that Xcode runs
Claude Desktop routing and MCP servers/Library/Managed Preferences/com.anthropic.claudefordesktop.plist, written by the network extension
Claude Code and Codex channelsManaged by Endpoint Guard for the signed-in user. See Claude and Codex Channels
MCP serversEach tool's MCP configuration file
Cursor hooks~/.cursor/hooks.json
Original tool settings~/.hypr/backups/
Enrollment identity and gateway settings~/.hypr/ and the keychain

Endpoint Configuration Locations has the complete file list. Restart a tool after its routing or MCP configuration changes. A running tool keeps its current settings until it restarts.

How Claude Desktop Signs In​

When Endpoint Guard routes Claude Desktop, Claude Desktop signs in to your gateway with the user's Claude Code sign-in. Claude Code must therefore be installed and signed in on the Mac with a claude.ai account. Endpoint Guard renews that sign-in by itself, and never asks the user.

Claude Desktop then names HYPR AgentPass as its provider, in its sidebar and account menu. While Claude Desktop is blocked from its provider, it works only through your gateway. It can still download Claude Code and check for its own updates.

If Claude Desktop does not use the gateway, or says its sign-in has expired, ask the user to open Claude Code so it renews its sign-in, then quit and reopen Claude Desktop.

What Developers See on a Mac​

Endpoint Guard tells the developer at the Mac when it blocks a tool or changes its setup. Share these messages with developers before you turn on enforcement, so they know what to do.

AI Agent Blocked​

When Endpoint Guard blocks a managed tool's direct connection to its provider, the AgentPass menu bar icon opens an AI Agent Blocked prompt. It reads Direct access to AI agents is not allowed per company policy., then names the tool and the host it tried to reach. The same prompt appears before anything is blocked, when a tool is running without routing at the moment a block goes in.

The prompt then says what to do:

The prompt saysWhat it means
… was already running when your organisation's settings were applied, so it hasn't picked them up.The tool started before Endpoint Guard routed it. Restart it, as the next line says
Quit it here and start it again to connect through the gateway.Quitting and starting the tool again is enough
Its terminal was also started before those settings, and a new tab inherits the same environment.The terminal or editor running the tool also started before the routing. Quit that application, named in the prompt, and reopen it, or log out and back in, then start the tool again. A new terminal tab is not enough
Quit it here and start it again. If it is still blocked, quit your terminal app and reopen it, then try once more.Try the tool first, then the terminal
Your organisation wants … to connect through its gateway. Set it up as your administrator describes …A tool AgentPass does not route. Set it up to use the gateway the way your organization describes
Use the approved launch method to route traffic through the corporate gateway.The blocked tool is no longer running. Start it the way your organization describes

When the tool is still running, the prompt offers Quit with the tool's name, which asks the tool to quit. A tool that is busy, for example with unsaved work, is not forced to quit. Dismiss closes the prompt. A dismissed prompt stays quiet for that tool for a short while.

Routed and Restart Alerts​

When Endpoint Guard routes a tool the developer is already using, an alert says that a restart is what is left to do:

  • … is now routed through the HYPR gateway, when the gateway routed the tool.
  • … is configured for the HYPR gateway, when the developer asked for it from the blocked prompt.

For a running application, the alert offers Restart with the tool's name, and Later. Otherwise, it offers OK. An application that does not quit when asked, usually because it is waiting for something to be saved, stays open, and the alert … is still running asks the developer to quit it and open it again.

An alert reading MCP servers updated means Endpoint Guard changed the MCP servers a tool is provided with. When a desktop is revoked, an alert reads This Mac is no longer managed by HYPR AgentPass. See When a Workstation Is Revoked.

Blocked AI SaaS Apps​

When a browser or app on the Mac reaches an AI SaaS app your organization blocks, an alert reads <domain> is blocked by your organisation. Its text is the coaching message you set for that app, followed by Use <alternative> instead. when you name an alternative. An app with no coaching message shows no alert. The alert appears at most once every 30 minutes for each domain, and never for an app you only observe. See SaaS Based AI.

Troubleshoot a Mac​

When something needs attention, the AgentPass menu lists the problem at the top, with what AgentPass does next. A problem shows only once it has lasted a minute. To see what happened and why, open the trace. See Trace What AgentPass Did. The following table lists each message, and what to do.

The menu saysWhat to do
Not set up — ask your administratorDeploy ~/.hypr/config.json with your gateway address. See Configure Enrollment. The reason follows in the menu. Nothing needs restarting
Not enrolled: no enrollment token is installedDeploy an enrollment token. See Configure Enrollment
Not enrolled: the gateway rejected the enrollment tokenCreate a new token in the console, and deploy it. Check that no older ~/.hypr/ssf-enrollment-token file is left over, since it takes precedence
Not enrolled: the gateway is not accepting enrollmentsCheck that Watch desktops is on, and that the token is active
Not enrolled: the gateway asked AgentPass to wait before trying again, or Not enrolled: the gateway answered with an errorNothing. AgentPass tries again by itself, and the menu says when. If it persists, contact HYPR Support
Not enrolled: the gateway refused this Mac's enrollmentCheck that the Mac's date and time are correct. ap-cli status says so when they are not. Otherwise, contact HYPR Support with the ap-cli status report
Cannot reach the HYPR gateway, or Offline from the HYPR gatewayCheck the Mac's network, VPN and firewall. AgentPass syncs again as soon as it can reach the gateway
The network filter is off — run Setup to turn it onChoose Run Setup…, and approve what macOS asks
The AgentPass service is not runningChoose Run Setup…. If it is waiting for approval, allow AgentPass in General → Login Items & Extensions. Otherwise, restart the Mac
The AgentPass service could not start after the update — log out and back inLog out of the Mac, and back in
This Mac was removed from AgentPass by an administratorThe desktop was revoked in the console. See When a Workstation Is Revoked

Remove Endpoint Guard​

How you remove Endpoint Guard depends on how it was installed.

Remove a HYPR Passwordless Installation​

Removing the application does not undo the routing and MCP settings it applied to each tool. Restore those first.

  1. In the Mac's own settings in the console, turn off Configure agents on this desktop, or turn on Restore this desktop's tools to their settings before AgentPass (once), and click Save. See Change One Desktop's Settings.
  2. Wait for the workstation's next check-in.
  3. Use the HYPR Passwordless uninstaller.
  4. Revoke the desktop on Desktops → Installation, so the gateway rejects its former identity. See Review and Revoke Desktops.

Remove a Standalone Installation​

For an installation from the installer package or the disk image, run the uninstaller included in AgentPass, from an administrator account:

sudo /Applications/AgentPass.app/Contents/Resources/agentpass-uninstall

The uninstaller asks before it starts, and removes Endpoint Guard for the user signed in at the Mac. In order, it:

  • Restores each tool's routing, MCP servers and hooks, and removes the egress blocks, as turning off Configure agents on this desktop does
  • Removes the Mac from your gateway, which then lists it as revoked
  • Quits AgentPass, removes its network filter and login items, and asks macOS to remove its network extension
  • Removes the enrollment identity, the workstation's signing key, the Endpoint Guard settings and logging configuration, and the application
OptionEffect
--yesStarts without asking, for example from your device-management tooling
--user <name>Removes Endpoint Guard for this user, in place of the user signed in at the Mac

When macOS asks, approve the removal of the network extension with an administrator's name and password. Your device-management tooling can allow the removal without asking, with a system extension policy that lists the AgentPass network extension as removable. Confirm the identifiers with your HYPR representative. Without the approval, the network extension stays installed, including across restarts, but it filters nothing, because the uninstaller removed its filter configuration.

The uninstaller restores the tools, and removes the Mac from the gateway, through the AgentPass service, so run it while AgentPass is running. If it could not restore them, it says so, and keeps ~/.hypr/backups/, which holds each tool's original settings. It also names any gateway setting left in the tools' managed settings, such as Claude Code's managed-settings.json. These files belong to your organization, so the uninstaller does not edit them.

When the uninstaller removes the Mac from the gateway, it reports The device was removed from the gateway. If the gateway cannot be reached, or the AgentPass service is not running, the uninstaller names the device at the end instead. Revoke that desktop on Desktops → Installation, so the gateway rejects its former identity. See Review and Revoke Desktops.