Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Version: 11.3.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​

Get the installer 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​

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. 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 gateway address when it connects, and checks for a newly delivered token every five minutes. 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
The AgentPass Setup window showing the network extension, traffic filter, AgentPass service and opens-at-login components ready

You can preapprove the extension, filter and login items through your device-management tooling. Confirm the current identifiers with your HYPR representative. Endpoint Guard needs neither Full Disk Access nor notification permission.

The AgentPass icon in the menu bar confirms the user interface is running. Its menu offers About AgentPass, Run Setup…, Share Diagnostics… and Share Logs…. 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. 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 → Extensions lists the AgentPass network extension.

    macOS System Settings listing the AgentPass network extension

After enrollment, the workstation appears in Agent Observability, and sends matching tool activity to Discovered.

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

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

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:

  • The workstation's Enforcement enabled control on the Managed Devices dashboard. 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:

  • Fail closed. 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.
  • Fail open. 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 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 fail open lifts or lifted the blocks.

When a Workstation Is Revoked​

When you revoke a workstation, Endpoint Guard stops managing it at its next check-in, as when you turn off Management enabled. 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
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.

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. On the Managed Devices dashboard, turn off Management enabled for the workstation, or click Restore tools to pre-HYPR config.
  2. Wait for the workstation's next check-in.
  3. Use the HYPR Passwordless uninstaller.
  4. Revoke the workstation on the Agent Observability tab, so the gateway rejects its former identity.

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 Management enabled does
  • 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 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.

The uninstaller cannot remove the workstation from the gateway. When it finishes, revoke the workstation on the Agent Observability tab, so the gateway rejects its former identity.