Plugin: Minimal Windows

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

This example shows the minimum valid plugin JSON for a Windows executable: autoStart enabled, a primary MQTT subscription, monitoring and auto-restart active, and permission to publish to KeeperLogger. Use it as a starting point and replace the placeholder values before deploying. For Linux and macOS variants, see Plugin: Minimal Linux and Plugin: Minimal macOS.

If your component runs on a schedule and exits rather than staying running, use a job task instead — start with Job: Minimal Windows.

The Plugin JSON

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

  "pluginType": "Executable",
  "executablePath": "bin/MyBridge/MyBridge.exe",
  "supportedPlatforms": ["Windows"],

  "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. This becomes the plugin's key in /api/PluginSettings/{id} and must match the filename: MyBridge.json for "id": "MyBridge". Do not change this after deployment without coordinating a migration — existing settings stored under the old ID will not carry over.
name	A human-readable name shown in logs and the admin view.
version	Your binary's semantic version. Update this with each release for diagnostics and change tracking.
executablePath	Path to your binary relative to the agent root, or an absolute path. The default Windows agent root is C:\Program Files\KeeperPrivilegeManager — so bin/MyBridge/MyBridge.exe resolves to C:\Program Files\KeeperPrivilegeManager\bin\MyBridge\MyBridge.exe.
Subscription.Topic	The primary MQTT topic for this plugin. By convention, use the plugin id. Must be unique among all plugins registered on the agent.
metadata.mqttTopics.publish	Every MQTT topic your binary publishes to. Include KeeperLogger if you publish log messages. Add any other output topics here — the broker enforces this list.
metadata.mqttTopics.subscribe	Every MQTT topic your binary subscribes to beyond the primary Subscription.Topic. The Commands/+ pattern is a convention for command-style topics — replace or remove it if your plugin does not use it.
startupPriority	Controls startup order relative to other plugins. Lower numbers start earlier. 60 is a reasonable default for a custom plugin that has no dependencies on other custom components.

How This Works

pluginType: Executable tells the orchestrator to launch the binary as a child process. This is the correct type for a standalone executable.

executablePath is relative to the agent root, not to the plugin directory. bin/MyBridge/MyBridge.exe places the binary outside the Plugins/ tree, which avoids the stricter certificate path checks that apply to executables located within plugin-related directories. Use an absolute path if your deployment layout does not follow this convention.

Subscription is the primary MQTT topic the orchestrator uses to identify this plugin. Set Qos: 2 for commands that must not be lost or duplicated. CleanSession: true is appropriate for most plugins — it means the broker discards any queued messages from previous sessions when the plugin reconnects, rather than replaying them.

metadata.mqttTopics must accurately reflect what your binary actually publishes and subscribes to. The broker enforces these lists at runtime — a publish or subscribe outside the declared topics will be denied. Unlike job tasks, plugins do not have a separate job-level mqttTopics block; all topic declarations live here under metadata.

autoStart: true causes the orchestrator to launch the plugin when the agent starts. Set this to false if the plugin should only run on demand or when triggered by a job — see Plugin: Manual Start for that pattern.

requiresMonitoring: true and autoRestart: true together tell the orchestrator to watch the process and restart it if it exits unexpectedly. Enable both for any production plugin that must stay running. If your plugin exits intentionally under certain conditions, ensure those exits use a recognizable exit code so you can distinguish expected shutdowns from crashes in the logs.

executionContext: Service runs the plugin as the agent service account — appropriate for background components that do not require an interactive user session.

Before You Deploy

1. Sign the binary. Plugin binaries on Windows are subject to stricter trust checks than job task binaries. Sign with an Authenticode certificate and add your thumbprint to Settings:AlternativeSignatures in appsettings.json if your deployment requires it.

2. Place the binary at the path resolved by executablePath before registering the plugin.

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. Dropping a plugin JSON file and restarting the agent is the typical mechanism, but your environment may have packaging or policy requirements.

5. Restart the agent service after placing both files so the orchestrator picks up the new plugin registration.

Verify

After the agent restarts, confirm the plugin started successfully by checking the agent logs for your plugin name, then verify MQTT connectivity by checking that your binary's KeeperLogger publishes are visible in the operator log view.

To read your plugin's effective settings:

Invoke-RestMethod -Method Get `
  -Uri "https://127.0.0.1:6889/api/PluginSettings/MyBridge" `
  -Certificate $pluginClientCert

This call requires Plugin-tier authentication — it must come from a process the agent launched, not from an arbitrary script. Run it from inside your plugin binary at startup to confirm the settings path is working end to end.