Check Repository Reference

A check repository is a source of monitoring-check definitions. octoja reads a repository, caches its check list, and shows the checks in the Check Library so you can assign them to devices. This reference covers the repository types, how octoja syncs them, and the exact layout a repository must publish. For the step-by-step of adding one, see Connect a Community Check Repository.

Repository types

How syncing works

• octoja re-syncs every URL-based repository automatically once an hour.
• The hourly sync only pulls when the repository's registry reports a generated timestamp newer than your last sync — an unchanged repository is skipped. The manual Sync now action always forces a full pull.
• Each repository is synced independently: one unreachable or malformed repository does not stop the others, and a failed sync keeps the previously cached check list intact.
• On every successful sync octoja replaces the cached entry for each check by id, so updates to a check propagate to the Check Library. A check that is removed from the registry stays in the Check Library until you delete the repository.
• A check's UI manifest is fetched again only when the registry advertises a uiVersion that differs from the cached one. A registry that leaves uiVersion out has every manifest fetched on every sync, because there is nothing to compare.
• If the repository uses HTTP basic authentication, the same credentials are sent on the registry fetch, on each check's manifest fetch, and on each binary download.

What a repository must publish

A check repository is a plain HTTP or HTTPS site. octoja resolves every path against the base URL you register — not against the baseUrl inside registry.json — and expects:

The whole site may sit behind a single HTTP basic-auth realm; provide the credentials when you connect the repository. A repository that asks for credentials has to be published over https://: octoja pairs a username with plain http:// only for loopback addresses such as localhost, and it accepts a password only alongside a username.

registry.json

{
  "version": "1.0",
  "generated": "2026-07-08T10:00:00Z",
  "baseUrl": "https://checks.example.com/",
  "checks": [
    {
      "id": "disk-temperature",
      "name": { "en": "Disk Temperature", "de": "Festplattentemperatur" },
      "description": { "en": "Reports the temperature of each drive.", "de": "Meldet die Temperatur jeder Festplatte." },
      "author": "Example MSP",
      "icon": { "type": "component", "library": "lucide", "name": "thermometer" },
      "category": "hardware",
      "tags": ["disk", "temperature"],
      "platforms": ["win-x64", "linux-x64"],
      "version": "1.2.0",
      "uiVersion": "9f2c41e7",
      "interval": 15,
      "timeoutSeconds": 120,
      "executionLocation": "Device",
      "executable": {
        "win-x64": {
          "downloadUri": "https://checks.example.com/checks/disk-temperature/1.2.0/win-x64/check.exe",
          "executableName": "check.exe",
          "fileType": "Exe",
          "executionType": "Exe"
        }
      }
    }
  ]
}

Check definition fields

Each entry in checks[] describes one check. Localized text fields (name, description) take an object with en, de, es, fr, it, and nl keys; en is used when the reader's language is missing.

executable entries

Per-check UI manifest (ui.json)

octoja fetches each check's manifest from checks/{id}/{version}/ui.json, where {version} is the check's version from the registry. The manifest defines two things:

• input — the parameters shown when the check is assigned to a device, keyed by parameter name. Each field declares its type, localized title and description, whether it is required, a default, and (for choices) its options. The field types are string (the fallback for an unrecognized type), text, password, integer, number, boolean, select, radio, and array; separator draws a divider instead of a field. Use password for secrets — the value is masked in the interface and stored with the assignment, so it never has to live in the repository. A field may also carry visibleIf to appear only when another field holds a given value.
• output — how the check's result renders: a detail renderer for the device's Checks tab, a history renderer for past results, and a widget renderer for dashboard tiles.

The input keys also decide whether a check is offered on network devices — devices monitored without an agent by one of your existing agents. A field of type string whose key is host, ip, ipaddress, target, url, endpoint, or address (matched regardless of capitalisation), or a field of type array with string items whose key is hosts, targets, or endpoints, marks the check as probing a remote target. Such a check appears in a network device's Add Check dialog; the field itself is hidden there, and octoja fills in the device's address on every run. The type has to match exactly: text does not qualify — despite the name it is not a text input but a static label rendered between fields — and neither does an endpoints array whose items are objects rather than strings. How the substitution behaves at run time — including the SNMP credential keys — is described in Custom Script.

A check whose UI manifest cannot be fetched is still listed. On its first sync it appears without custom input fields and result rendering; on a later sync the manifest octoja already holds stays in place, so a repository that goes quiet leaves a working renderer alone. One unreadable manifest does not stop the rest of the registry from syncing.

Check result protocol

Every check that runs on a device speaks the same protocol, whatever language it is written in. octoja launches it according to its executionType — powershell -ExecutionPolicy Bypass -File for PowerShell, bash for Bash, or the downloaded file itself for Exe — writes the check's configuration to standard input, and reads the result from standard output. Note that the PowerShell invocation does not use -NoProfile, so a machine-wide PowerShell profile runs before the check does.

checkResult values

Who writes the markers. A check published by a repository is downloaded and run unchanged, so its own script has to emit the markers around the payload. A custom script check built inside octoja is different: octoja wraps the script and emits the markers itself, and a script that writes them a second time breaks its own result. For a worked example of a repository check that implements this protocol, see Publish Your Own Community Check Repository.

Another octoja instance as a repository

An octoja instance can publish the custom checks you pick in exactly this format, so a second instance connects it as a Community repository. The details live under Settings → Check repository access on the publishing instance.

Connection test results

The Check connection button on the add and edit dialogs probes the repository through the same code path a real sync uses.

Permissions

Related articles

• Custom Script — build your own check inside octoja instead of hosting a repository.
• Checks — how checks work and the full built-in catalogue.