Job: Minimal Windows

Audience: Integrators deploying a custom executable on Windows endpoints.

This example shows the simplest valid job JSON for Windows: a single task that runs your binary on an interval schedule, as the agent service account, with permission to publish logs to KeeperLogger. Use it as a starting point and replace the placeholder values before deploying.

The Job JSON

{
  "id": "my-tool",
  "name": "My Tool",
  "description": "Runs MyTool on a 60-minute interval.",
  "enabled": true,

  "schedule": {
    "intervalMinutes": 60
  },

  "osFilter": {
    "windows": true,
    "linux": false,
    "macOS": false
  },

  "mqttTopics": {
    "allowedPublications": ["KeeperLogger"],
    "allowedSubscriptions": []
  },

  "parameters": [],

  "tasks": [
    {
      "id": "run-tool",
      "name": "Run tool",
      "ExecutionType": "Service",
      "command": "MyTool",
      "executablePath": "C:\\Program Files\\KeeperPrivilegeManager\\Jobs\\bin\\MyTool\\MyTool.exe",
      "arguments": "--keeper-api-base={KeeperApiBaseUrl}",
      "timeoutSeconds": 3600,
      "continueOnFailure": false,
      "scriptType": "Auto"
    }
  ]
}

What to Change

Field

What to put here

id	A unique identifier for this job. Use hyphens — no underscores. The filename must match: my-tool.json for "id": "my-tool".
name	A human-readable name shown in logs and the admin view.
description	Optional, but useful for anyone maintaining the deployment later.
schedule.intervalMinutes	How often to run, in minutes. 60 = every hour. This is time between runs, not a clock-aligned schedule — see schedule options for cron and calendar alternatives.
tasks[0].command	The name of your binary without a path or extension. The agent resolves Jobs\bin\{command}\{command}.exe automatically.
tasks[0].executablePath	The full path to your binary on the endpoint. Replace MyTool with your executable name throughout.
tasks[0].arguments	Any flags your binary accepts. Keep {KeeperApiBaseUrl} — the agent substitutes the local HTTPS API base URL here so your binary can call Plugin Settings at runtime.
tasks[0].timeoutSeconds	Maximum run time before the agent kills the task. 3600 = one hour. Set this to something meaningful for your tool.

Leave osFilter, mqttTopics, ExecutionType, continueOnFailure, and scriptType as shown for a standard Windows background task.

How this Works

osFilter tells the agent to only run this job on Windows endpoints. When the job is deployed to a mixed fleet, agents on Linux and macOS will skip it. The validator also skips binary existence checks on non-matching platforms, which means you can register this job from a Windows machine without worrying about Linux paths.

ExecutionType: Service runs the task as the agent service account — the right choice for any background tool that needs machine-wide access but not an interactive user session. The process is registered in the agent's launched-process registry immediately on start, which grants it access to MQTT and Plugin Settings without needing a certificate check.

mqttTopics.allowedPublications grants your task permission to publish to the KeeperLogger topic. The MQTT broker enforces this list — without it, connection succeeds but publish calls are denied. If your tool does not publish to MQTT at all, you can remove the mqttTopics block entirely, but then the agent will not inject KEEPER_JOB_ID or KEEPER_JOB_NAME as environment variables.

{KeeperApiBaseUrl} is replaced at run time by the agent with the local HTTPS API base URL (typically https://127.0.0.1:6889). Your binary reads this from its command-line arguments and uses it to call GET /api/PluginSettings/KeeperPrivilegeManager to fetch the MQTT broker address.

Before you Deploy

1. Deploy the binary first. Place MyTool.exe at the executablePath on the endpoint before registering the job. The validator checks that the binary exists at the time POST /api/Jobs is called.

2. Confirm the binary path. The default agent install root on Windows is C:\Program Files\KeeperPrivilegeManager. If your deployment uses a different root, update executablePath accordingly.

3. Save the file as {id}.json. If you change the id field, the filename must match. A job with "id": "my-tool" must be saved as my-tool.json.

Deploy

Validate the JSON against a live agent before saving:

Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs/validate" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body (Get-Content -Raw .\my-tool.json)

Then create the job:

Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body (Get-Content -Raw .\my-tool.json)

Trigger a manual run to confirm everything is working:

Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs/my-tool/trigger" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body "{}"

For fleet deployments, use a JobUpdate policy via the Keeper console instead of calling the API directly on each endpoint. Contact your Keeper administrator for the current policy schema.