Check Repository Reference

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.
• 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. Starting from the base URL you register, octoja expects:

The whole site may sit behind a single HTTP basic-auth realm; provide the credentials when you connect the repository.

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",      "interval": 15,      "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, fr, and nl keys; en is used when the reader's language is missing.

executable entries

Per-check UI manifest (ui.json)

For each check, octoja fetches checks/{id}/{version}/ui.json. 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.
• 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.

A check whose UI manifest cannot be fetched is still listed, but without its custom input fields and result rendering.

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

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