Check Repository Reference

Repository types, how octoja syncs them, and the registry.json layout a check repository must publish so its monitoring checks appear in your Check Library.

Written By Stefan Steuer

Last updated 8 days ago

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

TypeWhere it comes fromSynced from a URL?
Officialoctoja's own maintained repository at https://repo.octoja.com. Present by default and read-only.Yes — managed by octoja
CommunityA repository you connect by URL. Editable, syncable, and removable.Yes
CustomYour own custom checks, built inside octoja under Configuration → Custom Checks.No — they already live in octoja

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:

Path (relative to the base URL)What it is
registry.jsonThe index of every check the repository offers. Fetched first on every sync.
checks/{id}/{version}/ui.jsonThe UI manifest for one check version — the input fields and result rendering.
each executable's downloadUriThe check binary the agent downloads and runs on the device.

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

registry.json

FieldTypeDescription
versionstringThe registry's own version label.
generatedtimestampWhen the registry was generated. octoja compares this to the last sync to decide whether the hourly sync needs to pull. Bump it whenever you publish a change.
baseUrlstringThe repository's base URL.
checksarrayOne entry per check the repository offers (see below).
{  "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.

FieldTypeDescription
idstringStable identifier for the check. Used as the key in the Check Library and as the path segment for its manifest and binaries.
namelocalized stringDisplay name shown in the Check Library.
descriptionlocalized stringShort description shown on the check card.
authorstringAuthor or maintainer, shown on the card.
iconobjectIcon descriptor. { "type": "component", "library": "lucide", "name": "<lucide-icon>" } for a built-in icon, or { "type": "embedded", "name": "<svg-or-base64>" } for an inline image.
categorystringGrouping in the Check Library (for example hardware, network, services, security).
tagsstring arrayFree-form tags used by the library search and filters.
platformsstring arrayRuntime identifiers the check supports (for example win-x64, linux-x64, osx-arm64).
versionstringThe version octoja offers. Also the {version} path segment for the UI manifest and binaries.
intervalnumberDefault run interval in minutes.
executionLocationstringDevice (default) runs the check on the agent; Server evaluates it server-side. Omit for a normal device check.
executableobjectMap of platform identifier to the binary for that platform (see below).

executable entries

FieldDescription
downloadUriAbsolute URL the agent downloads the check binary from.
executableNameFile name to store the binary as on the device.
fileType / executionTypeTell the agent what kind of artifact it is and how to run it.

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.

ResultMeaning
Connected — N checks foundregistry.json was fetched and parsed. N is the number of checks it lists.
Repository unreachableoctoja could not reach the URL — wrong address, network/DNS/TLS problem, or rejected basic-auth credentials.
Invalid registryThe URL responded, but no valid registry.json could be read at the base URL.

Permissions

PermissionRequired for
Check Repository Management (check-repositories.manage)Adding, editing, deleting, and syncing check repositories.
Monitoring Check Management (monitoring-checks.manage)Browsing the Check Library and assigning the checks it lists.