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.
- Double-click the installer package. It opens at the Configuration step.
- In AgentPass server, enter the gateway address. It starts with
https://. - In Enrollment token, paste the token. It starts with
ssf_. - Select I agree to the End User License Agreement, and click Continue.
- 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 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.
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:
- In the disk image window, open Quit AgentPass. The running components stop.
- 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.
{
"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.
- In the AgentPass Setup window, click Run Setup.
- Approve each macOS prompt. The setup window confirms each component as it becomes ready.
The setup window lists these components.
| Setup window | Purpose | Approval |
|---|---|---|
| Network extension | Runs the Endpoint Guard network extension | Allow the system extension when macOS asks |
| Traffic filter | Attributes network connections and enforces configured egress controls | Allow AgentPass to filter network content |
| AgentPass service | Enrolls the Mac, discovers AI tools and applies managed configuration. Restarts automatically if it stops | None |
| Opens at login | Opens the AgentPass menu bar app at login | None |
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.
Confirm the Installation
Confirm the installed components in System Settings:
-
Network → Filters lists HYPR AgentPass as an enabled content filter.
-
General → Login Items & Extensions lists AgentPass under Open at Login and App Background Activity.
-
General → Login Items & Extensions → Extensions lists 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.
| Section | What it answers |
|---|---|
| AgentPass | Which version is installed, and whether the network extension is active with a filter configuration that belongs to Endpoint Guard |
| Gateway | Which gateway address is in force and where it came from, whether the gateway answers, and whether an enrollment token is present |
| Enrollment | Whether the workstation is enrolled, and which version of the managed configuration it applied |
| Network filter | Whether 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 |
| Agents | For 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.
| Command | Purpose |
|---|---|
ap-cli status --json | The same report as JSON, to attach to a support request or read from a script |
ap-cli version | The installed and active versions of the application and the network extension |
sudo ap-cli logs brain --last 2h | Recent log entries from the service that applies managed configuration |
ap-cli reenroll | Enrolls 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.
| Configuration | Location |
|---|---|
| Claude Code routing | ANTHROPIC_BASE_URL in the user's login session or an existing enterprise managed-settings.json file |
| Codex routing | openai_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 channels | Managed by Endpoint Guard for the signed-in user. See Claude and Codex Channels |
| MCP servers | Each 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.
- On the Managed Devices dashboard, turn off Management enabled for the workstation, or click Restore tools to pre-HYPR config.
- Wait for the workstation's next check-in.
- Use the HYPR Passwordless uninstaller.
- 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
| Option | Effect |
|---|---|
--yes | Starts 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.
Related
- Endpoint Guard — how workstation discovery, reporting and controls fit together
- Endpoint Platform Support — compare macOS and Windows capabilities
- Managed Desktop Tools — configure routing, MCP tools and egress controls