Plugin: Minimal macOS

Audience: Integrators registering a long-running managed plugin on macOS endpoints.

This is the macOS variant of Plugin: Minimal Windows. The plugin structure and field meanings are identical — the differences are the binary path, supportedPlatforms, and macOS-specific signing requirements that are stricter here than on any other platform. Read the Windows page first for the full explanation of each field; this page covers only what changes on macOS.

The Plugin JSON

{
  "id": "MyBridge",
  "name": "My Bridge",
  "description": "Long-running bridge component.",
  "version": "1.0.0",

  "pluginType": "Executable",
  "executablePath": "bin/MyBridge/MyBridge",
  "supportedPlatforms": ["macOS"],

  "Subscription": {
    "Topic": "MyBridge",
    "Qos": 2,
    "CleanSession": true
  },

  "metadata": {
    "mqttRole": ["subscriber", "publisher"],
    "mqttTopics": {
      "publish": ["KeeperLogger"],
      "subscribe": ["MyBridge", "MyBridge/Commands/+"]
    }
  },

  "startupPriority": 60,
  "autoStart": true,
  "executionContext": "Service",
  "requiresMonitoring": true,
  "autoRestart": true
}

What to Change

Field

What to Put Here

id	A stable, unique identifier matching the filename: MyBridge.json for "id": "MyBridge".
executablePath	Path to the binary relative to the agent root, with no .exe extension. The default macOS agent root is /usr/local/KeeperPrivilegeManager — so bin/MyBridge/MyBridge resolves to /usr/local/KeeperPrivilegeManager/bin/MyBridge/MyBridge. Confirm the install root with your administrator.
supportedPlatforms	["macOS"] for a macOS-only plugin.
Subscription.Topic	The primary MQTT topic for this plugin. By convention, use the plugin id.
metadata.mqttTopics.publish	Every topic your binary publishes to. Include KeeperLogger if you publish log messages.
metadata.mqttTopics.subscribe	Every topic your binary subscribes to beyond the primary Subscription.Topic.

No .exe extension. The binary name in both executablePath and the directory path has no extension, identical to Linux.

File permissions. The binary must be executable by the agent service account before the orchestrator can launch it:

chmod +x /usr/local/KeeperPrivilegeManager/bin/MyBridge/MyBridge

Signing and notarization are mandatory. This is the most important macOS-specific requirement and it applies before the agent ever attempts to launch the binary. Gatekeeper blocks unsigned or unnotarized binaries at the OS level — the orchestrator will not get the chance to register or start a binary that Gatekeeper has quarantined. Sign with an Apple Developer ID certificate and submit for notarization as part of your release process. Unlike job task binaries, plugin binaries are also subject to KEPM's stricter plugin path trust checks, so signing is doubly important here.

After signing, add your certificate thumbprint to Settings:AlternativeSignatures in appsettings.json if your deployment requires explicit thumbprint registration for MQTT or Plugin Settings access outside an orchestrator-launched context.

autoRestart and launchd. On macOS, the KEPM agent typically runs as a launchd daemon. If autoRestart: true is set and the plugin exits unexpectedly, the orchestrator restarts it independently of launchd. Rapid restart loops will generate log volume and CPU load just as on Linux — ensure your plugin exits cleanly under expected shutdown conditions and emits a clear log message before doing so.

Before You Deploy

1. Sign and notarize the binary before placing it on any macOS endpoint. This must happen before deployment — it cannot be done after the fact on the target machine.

2. Place the binary at the path resolved by executablePath and set executable permissions with chmod +x.

3. Place the JSON file at {AgentRoot}/Plugins/MyBridge.json. The filename must match id.

4. Coordinate with your administrator on the supported insertion path for your environment.

5. Restart the agent so the orchestrator picks up the new plugin registration:

sudo launchctl stop com.keeper.privilegemanager
sudo launchctl start com.keeper.privilegemanager

Confirm the launchd service label with your administrator — the exact label may differ depending on how the agent was packaged for your deployment.

Verify

After the agent restarts, check the agent logs for your plugin name to confirm it started. Then verify Plugin Settings are reachable from inside your binary at startup:

curl -s https://127.0.0.1:6889/api/PluginSettings/MyBridge \
  --cert /path/to/client.pem \
  --key /path/to/client.key \
  --cacert /path/to/ca.pem

This call requires Plugin-tier authentication and will return 403 from an arbitrary shell session. Run the equivalent call from inside your plugin binary as a startup smoke test.