Overview
This page explains the concepts and moving parts behind a KEPM integration so you have a mental model before writing any code or JSON. If you have not read the Integration landing page yet, start there — it defines the two integration patterns and lists what you need to collect from your deployment team before you begin.
Key Terms
Understanding how KEPM uses these terms will prevent confusion as you read the guides.
Job — A JSON document stored as {job-id}.json under the agent's Jobs/ directory. A job defines when something runs (a schedule, a startup event, or a named event topic) and what runs (one or more tasks). Jobs are the primary way to schedule and drive custom executables.
Task — One step inside a job. A task points at an executable or script, specifies how to run it (ExecutionType), passes arguments, sets a timeout, and defines what to do if the step fails. Most custom integrations have exactly one task per job.
Plugin — A component registered under Plugins/{PluginId}.json that the agent manages as a first-class process. Plugins have an agent-controlled lifecycle (start, monitor, restart) and subscribe to MQTT topics under their own identity. This is a distinct concept from a job task binary — your executable is not a plugin simply because it is deployed alongside the agent.
KeeperLogger — A built-in agent component that subscribes to the MQTT topic KeeperLogger and writes incoming messages to the agent's log pipeline. Your executable publishes structured JSON to that topic; the agent delivers those messages to wherever operators see logs. This is the primary way a custom job task communicates output back to the platform.
MQTT broker — A local message broker that the agent runs on the loopback interface (default 127.0.0.1:8675, TLS). Local components — including your task binary — connect to it to publish and subscribe. Access is controlled by process trust: only executables the agent has launched or explicitly allow-listed can connect.
Process trust — The mechanism by which the agent decides which local processes may connect to its MQTT broker and call Plugin-tier HTTPS endpoints. When the job runner starts your binary, it registers that process immediately so that MQTT and HTTPS calls from your binary are authorized. If your binary starts some other way (manually, from a script), it must pass a certificate check instead — see the Custom Job Integration Guide for the full details.
Integrations Flow
The flow below describes what happens from the moment your job is deployed to the moment a log line appears in the operator's view.
The agent is the gatekeeper. Your binary gets process trust, MQTT access, and runtime settings because the agent started it — not because of anything your binary does on its own first.
You do not hard-code the broker address. Your binary asks the agent at startup by calling Plugin Settings over HTTPS. The agent returns the current broker.host and broker.port.
Logging flows through MQTT, not stdout. Your binary publishes structured JSON to the KeeperLogger MQTT topic. The agent handles delivery from there.
Job JSON controls MQTT permissions. Your binary can only publish to topics explicitly listed in the job's mqttTopics.allowedPublications. The broker enforces this — permissions are not inherited or assumed.
Jobs vs. Plugins
The two integration patterns share the same agent and the same MQTT broker, but they serve fundamentally different purposes.
Use a Job When:
Run a tool on a schedule or at agent startup
Define schedule.intervalMinutes and/or an events entry with eventType: Startup
Publish logs to KeeperLogger
Set mqttTopics.allowedPublications: ["KeeperLogger"] on the job
Support multiple operating systems
Set osFilter so each platform only runs the task that matches
Pass runtime configuration to your binary
Use {KeeperApiBaseUrl} and other variable substitutions in tasks[].arguments
Deploy the binary without plugin overhead
Place it under Jobs/bin/{CommandName}/ — no plugin JSON required
A job task binary does not need to be long-running. The expected pattern is: start, do work, exit with a meaningful exit code. The agent records the exit code, captures output, and moves on.
Use a Plugin When:
Keep a process running continuously
Plugin JSON supports autoStart: true and requiresMonitoring: true
Have the agent restart your process on failure
Set autoRestart: true in the plugin JSON
Subscribe to MQTT topics as a named, persistent identity
A plugin has a primary Subscription and its own topic namespace
Store per-component settings retrievable by plugin ID
Plugin settings are readable via GET /api/PluginSettings/{yourPluginId}
Ship a component that behaves like a native part of the agent
Plugin packaging, signing, and lifecycle expectations match bundled components
When to Use Both
The only time you need both patterns is when you genuinely have two separate lifecycles: a long-running daemon registered as a plugin (always on, monitored) and a separate scheduled job that performs periodic work using a different binary.
Avoid registering the same executable as both a plugin and a job task. Doing so can produce duplicate processes, conflicting MQTT client IDs, and ambiguity about which configuration path owns the binary's settings.
Quick Reference
Is Plugins/{id}.json required for a job task?
No. A job only needs Jobs/{id}.json and the deployed binary.
Can a job task publish to MQTT?
Yes, by declaring mqttTopics.allowedPublications on the job.
Can a job task call Plugin Settings over HTTPS?
Yes, when started by the agent (Plugin-tier auth).
When is plugin registration required?
Only when you need agent-managed lifecycle, persistent MQTT subscription, or plugin-scoped settings.
What the Agent Provides to Your Process
When the agent starts your binary as a job task, it sets the following environment variables — but only when the job defines mqttTopics with at least one allowed publication or subscription:
KEEPER_JOB_ID
The id field from your job JSON
Required when forming the MQTT client ID
KEEPER_JOB_NAME
The name field from your job JSON
Useful for log messages and diagnostics
Your binary also receives {KeeperApiBaseUrl} as a substituted argument value (not an environment variable) if you include it in tasks[].arguments. Use it as the base URL for Plugin Settings HTTPS calls.
The agent does not inject broker.host, broker.port, or MQTT connection details as environment variables. Your binary is expected to fetch those at runtime from Plugin Settings.
Now What?
For a scheduled or event-driven tool — the most common case — continue to the Custom Job Integration Guide. It covers every step from building and deploying the binary, to authoring the job JSON, to connecting to MQTT and publishing structured logs.
For a managed, long-running component, go to the Custom Plugin Integration Guide.
When you are ready to script job deployment or call Plugin Settings from inside your binary, the HTTP Reference has the endpoints, authorization tiers, and request shapes you need.
Last updated