Skip to the content

Turn on the macOS sentinels

Activate AgentGarm's Endpoint Security and Network Extension on a Mac, approve them by MDM or by hand, and check that they hold the agent's processes.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Activate AgentGarm's two system extensions on a Mac with a root install: the Endpoint Security sentinel, which checks every program and protected file an agent's processes reach and keeps them from stopping AgentGarm, and the Network Extension, which sends the agent's traffic through AgentGarm's proxy even when the agent unsets its proxy settings. Approve them by MDM or in System Settings, check that they are connected, and choose what happens to agents while they are down.

1. Know what the sentinels add, and what is still pending

The Endpoint Security sentinel, agentgarm-es, runs as root inside a system extension. For every process of a governed task, including ones the agent starts outside its hooks and sandbox, it answers each program start against the task's command rules on the full argument list, each file open against its file rules, and refuses signals that would stop agentgarmd, agentgarm-session or the sentinel itself. It also records the files a shell command creates, writes, renames or deletes, so they reach the task's change list. The Network Extension redirects the task's TCP flows to AgentGarm's proxy and refuses its UDP unless the policy lists the destination; traffic from processes outside governed tasks passes untouched.

Both are built, not yet claimed. With the sentinel, commands and files can rate A and the network B; until the gate is recorded this release rates nothing A. The Network Extension needs nothing from Apple beyond AgentGarm's Developer ID. Endpoint Security needs an entitlement only Apple grants, and AgentGarm has not received it yet, so on a release build the sentinel reports that it is not entitled and stays off. Until the grant, it runs only in a development build on a dedicated virtual machine with System Integrity Protection off; never turn that off on a Mac that matters.

See also

Check that protection is on

See whether AgentGarm's services are up, what assurance level each agent session has and why, and what to do about a bypass alert.

2. Install the macOS package and the service

The sentinels need the root install from the signed .pkg (install on macOS): it places /Applications/AgentGarm.app, which carries both extensions, com.agentgarm.AgentGarm.EndpointSecurity and com.agentgarm.AgentGarm.NetworkExtension. macOS runs a system extension only from an app in /Applications, so leave the app where the package puts it. A no-root install has no sentinel. Start the service with sudo agentgarmd install. It also asks macOS to load both extensions and prints what macOS answered for each, then the self-check; on a Mac without the profiles below, macOS answers that the extensions wait for your approval.

sudo agentgarmd install

3. Approve the extensions and Full Disk Access

On a Mac your organisation manages, deploy AgentGarm's three configuration profiles: agentgarm-system-extensions.mobileconfig allows both extensions for AgentGarm's Apple team without a prompt and stops the user from turning them off; agentgarm-pppc-fda.mobileconfig grants Full Disk Access to the Endpoint Security extension and to /usr/local/bin/agentgarmd, pinned to AgentGarm's Developer ID; and agentgarm-transparent-proxy.mobileconfig configures the transparent proxy for AgentGarm's signed provider only. The profiles approve the extensions in advance; macOS still loads them only when AgentGarm asks, which sudo agentgarmd install does, so a managed Mac needs no extra step once the profiles are there. If the profiles arrived after the install, run /Applications/AgentGarm.app/Contents/MacOS/AgentGarm activate-sysext to ask again.

On a Mac without MDM, approve both extensions in System Settings, General, Login Items & Extensions, and give the Endpoint Security extension Full Disk Access in Privacy & Security, Full Disk Access. Without the profiles the Mac counts as degraded until you have done both. The same app's sysext-status says whether each extension is missing, staged, waiting for you, or enabled, with the setting that fixes it.

See also

Deploy AgentGarm with MDM

Roll AgentGarm out to managed Macs, Linux machines and Windows PCs: the packages, the services, the macOS approvals and the browser extension.

4. Check that the sentinels are connected

agentgarm status prints a sentinel line for each extension that has reported to agentgarmd: sentinel endpoint_security [ok] and sentinel network_extension [ok] when both are connected. For the Endpoint Security extension, [FAIL] comes with the cause and the System Settings page that fixes it: the entitlement missing or the extension not approved, Full Disk Access not granted, or the client not connected; for the Network Extension it says to approve the extension or restart it. [WARN] means it is connected but missed deadlines or lost events. The Endpoint Security sentinel probes its own access again every 10 minutes and after the Mac wakes, so a Full Disk Access grant or MDM profile removed later shows here too.

agentgarm status

5. Choose what happens while a sentinel is down

The sentinel section of the host policy, default.yaml, decides it. With on_unavailable: alert, the default, agents still start, and any task that runs while a sentinel is disconnected or unhealthy is demoted to C for the rest of its life, with a host-wide alert; a sentinel that comes back does not raise it again. With on_unavailable: deny, agentgarmd refuses to start an enforce-mode task until every required sentinel is connected and healthy, and records the refusal; an unreadable default.yaml counts as deny. on_deadline_miss: fail_closed denies a governed process's request the sentinel could not answer in time, while other processes are allowed, and tamper_protection keeps the protection below on. agentgarmd reads the policy when it starts, so restart it after an edit.

sentinel:
  on_unavailable: alert
  on_deadline_miss: fail_closed
  deadline_headroom_ms: 250
  tamper_protection: true
sudo launchctl kickstart -k system/com.agentgarm.agentgarmd

6. Know what you see when a sentinel acts

Launch the agent with agentgarm run, so the sentinel knows the task's processes from the first one. When a command or file rule denies, the program does not start or the file does not open, and the agent's process sees the call fail as not permitted. The deny is recorded in the audit log as the OS sentinel's. A process of the task that writes AgentGarm's state or policies, an agent's managed settings or hook files, such as .claude/settings.json or .cursor/hooks.json, or signals one of AgentGarm's processes is refused in audit mode too, and the dashboard shows a tamper alert.

The sentinel answers from the last policy it received, so it keeps refusing with agentgarmd stopped. Losing its entitlement, Full Disk Access or connection, or the Network Extension falling behind, demotes every running task to C at once, with an alert naming the cause. While the Network Extension runs, a task's traffic reaches the proxy even when the agent unsets HTTPS_PROXY; stopping agentgarm-session then blocks that traffic rather than letting it out, and QUIC is always refused.

agentgarm run -- claude

See also

Trace what one agent task did

Find an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last.