# 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](/keeperpam/endpoint-privilege-manager/integrations.md) 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](/keeperpam/endpoint-privilege-manager/integrations/custom-job-guide.md) 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. ``` ┌─────────────────────────────────────────────────────────────────┐ │ KEPM Agent (on the endpoint) │ │ │ │ Job runner reads Jobs/{job-id}.json │ │ │ │ │ ├─ Evaluates triggers (schedule / Startup / event) │ │ │ │ │ └─ Starts your binary as a task process │ │ │ registers PID → process trust │ │ │ sets KEEPER_JOB_ID, KEEPER_JOB_NAME │ │ │ │ │ │ Your binary runs │ │ │ │ │ │ │ ├─ GET /api/PluginSettings/ │ │ │ │ KeeperPrivilegeManager │ │ │ │ (Plugin-tier HTTPS) │ │ │ │ → reads broker.host, broker.port │ │ │ │ │ │ │ └─ Connects to MQTT broker (TLS, loopback) │ │ │ publishes to KeeperLogger │ │ │ │ │ KeeperLogger component │ │ subscribes to "KeeperLogger" topic │ │ → writes messages to agent log pipeline │ │ → operators see log output │ └─────────────────────────────────────────────────────────────────┘ ``` **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:
You need to...How the job covers it
Run a tool on a schedule or at agent startupDefine schedule.intervalMinutes and/or an events entry with eventType: Startup
Publish logs to KeeperLoggerSet mqttTopics.allowedPublications: ["KeeperLogger"] on the job
Support multiple operating systemsSet osFilter so each platform only runs the task that matches
Pass runtime configuration to your binaryUse {KeeperApiBaseUrl} and other variable substitutions in tasks[].arguments
Deploy the binary without plugin overheadPlace 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:
You need to...Why a plugin fits
Keep a process running continuouslyPlugin JSON supports autoStart: true and requiresMonitoring: true
Have the agent restart your process on failureSet autoRestart: true in the plugin JSON
Subscribe to MQTT topics as a named, persistent identityA plugin has a primary Subscription and its own topic namespace
Store per-component settings retrievable by plugin IDPlugin settings are readable via GET /api/PluginSettings/{yourPluginId}
Ship a component that behaves like a native part of the agentPlugin 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
QuestionAnswer
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:
VariableValueUse
KEEPER_JOB_IDThe id field from your job JSONRequired when forming the MQTT client ID
KEEPER_JOB_NAMEThe name field from your job JSONUseful 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](/keeperpam/endpoint-privilege-manager/integrations/custom-job-guide.md). 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](/keeperpam/endpoint-privilege-manager/integrations/custom-plugin-guide.md). When you are ready to script job deployment or call Plugin Settings from inside your binary, the [HTTP Reference](/keeperpam/endpoint-privilege-manager/integrations/http-reference-guide.md) has the endpoints, authorization tiers, and request shapes you need. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.keeper.io/keeperpam/endpoint-privilege-manager/integrations/overview.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.