Services
Show a computer's services, timers, backups and other checks, and what's busy, from a provider command, and run their actions.
The services module shows what a computer is doing beyond its hardware: long-running services, timers and the jobs they start, and checks such as a backup’s newest snapshot or a sync tool’s folders. Each item has a health, a summary, whether it’s busy, and its own stats, notes and lists.
System Bridge doesn’t watch services itself. It reads them from a provider: a command you set up that prints what it knows in the provider document. dot’s dot services export is one, and any tool or script can be another.
Adding a provider
Providers are set in the services section of settings.json in the settings directory. Each has an id, a list command and an act command, each written as a list of the program and its arguments:
{
"services": {
"providers": [
{
"id": "dot",
"list": ["dot", "services", "export"],
"act": ["dot", "services", "act"]
}
]
}
}
idis how clients refer to the provider: letters, digits,-and_.listprints the provider document. It’s required.actruns an item’s actions, and can be left out, in which case the provider’s items have no actions.
The program runs directly, not through a shell. A name without a path, such as dot, is looked up on the PATH System Bridge runs with, which for a service can be shorter than your shell’s, so a full path is safer.
System Bridge reads the settings file before each read, so a change takes effect within a minute, without a restart.
How it’s read
System Bridge runs every provider’s list command once a minute, all at once, and merges what they report in the order they’re set. Each run can take up to 15 seconds and print up to 1 MB.
A provider that fails, by exiting with an error, timing out, or printing something that isn’t a version 1 document, keeps the items it last reported, marked stale unless they were already worse. Its busy list stays too, so a provider that can’t be read never looks like it has nothing busy. Its error is in the module’s providers list, with when it last read.
The module’s data, from GET /api/data/services, the WebSocket or the clients, looks like this:
{
"providers": [{ "id": "dot", "updated": 1763600000000, "error": null }],
"items": [
{
"provider": "dot",
"id": "kopia-offsite",
"label": "Off-site backup",
"kind": "timer",
"health": "running",
"summary": "Uploading to B2",
"busy": true,
"last_run": 1763599500000,
"last_success": 1763513100000,
"next_run": 1763685900000,
"progress": 0.4,
"stats": [],
"notes": [],
"lists": [],
"actions": [{ "id": "start", "label": "Run now", "confirm": null, "disabled": null }]
}
],
"busy": [{ "provider": "dot", "item": "kopia-offsite", "label": "Off-site backup", "since": 1763599500000 }],
"errors": []
}
Each item, busy entry and error names its provider, as two providers can use the same item ID. With no providers, every list is empty.
Seeing services
- Web client: the Services page shows each item with its health, summary, progress, stats, notes and lists, and any provider that failed. While anything is busy, a Busy chip in the header links to it.
- CLI:
system-bridge client services listprints a table of the items, then any errors; add--jsonfor the module’s data.system-bridge client services watchprints the data as NDJSON each time it changes. See the CLI. - MCP: an assistant can read them with
system_bridge_list_services. - Omarchy: the plugin’s Services view, with what’s busy and anything that failed on its overview, and an hourglass in the bar while anything is busy.
Running actions
An item’s actions are what clients can ask its provider to do, such as starting a backup or verifying it. System Bridge runs one with the provider’s act command, with the item’s ID and the action’s ID added to the end, so for the dot provider above, Run now on kopia-offsite runs dot services act kopia-offsite start.
- Only an action in the latest data that isn’t
disabledruns, so a provider decides what can run. The provider should check the item and action again itself. - An action can run for up to 5 minutes. When it finishes, System Bridge tells every connected client how it went, whichever one ran it: whether it worked, a summary (the first line it printed, or why it failed) and its output, cut off at 64 KB. Then it reads the services again, so the change shows straight away.
- An action with a
confirmquestion asks it first in the web client, the CLI and the Omarchy plugin, and an assistant is told to ask you. System Bridge can’t check a client asked.
Run one from:
- Web client: the item’s buttons on the Services page. A disabled one says why when you hover over it. The last result, from any client, shows under them with its output.
- CLI:
system-bridge client services act <provider> <item> <action>, which prints the output and exits with 1 if it failed. It asks an action’s question first, or runs it straight away with--yes. - API: send
SERVICE_ACTION. - MCP:
system_bridge_run_service_action, which waits for it to finish. - Omarchy: select the action in the plugin’s Services view. One with a question shows it first and runs when you select it again.
Each run is logged at the INFO level with the command, and who asked for it.
The provider document
list prints one JSON document, version 1. System Bridge owns it, so any tool can implement it. Keys it doesn’t know are ignored, so a provider can add its own.
{
"version": 1,
"updated": 1763600000000,
"busy": [{ "item": "kopia-offsite", "label": "Off-site backup", "since": 1763599500000 }],
"items": [
{
"id": "kopia-offsite",
"label": "Off-site backup",
"kind": "timer",
"health": "running",
"summary": "Uploading to B2",
"busy": true,
"lastRun": 1763599500000,
"lastSuccess": 1763513100000,
"nextRun": 1763685900000,
"progress": 0.4,
"stats": [{ "id": "r2_used", "label": "R2 used", "value": 7.1, "unit": "GB", "kind": "size" }],
"notes": ["B2 is capped at the free 10 GB"],
"lists": [{ "id": "sources", "label": "Sources", "items": [{ "label": "Photos", "value": "02:27" }] }],
"actions": [
{ "id": "start", "label": "Run now" },
{ "id": "verify", "label": "Verify", "confirm": "Read back 10% of the files?", "disabled": "Runs after the upload" }
]
}
],
"errors": [{ "source": "services.d/foo.yml", "message": "Unknown key busyy" }]
}
Times are Unix milliseconds.
| Key | Meaning |
|---|---|
version |
Always 1. Any other version is a failed read. |
updated |
When the provider made the document. |
busy |
What’s busy: each entry’s item, its label and since when. |
items |
The services, timers and checks. |
errors |
Problems the provider wants shown, such as a registration it couldn’t read: a source and a message. |
Each item has:
| Key | Meaning |
|---|---|
id |
Required, and unique within the provider. |
label |
Its name. The ID when left out. |
kind |
service, timer or check, or another kind of the provider’s own. |
health |
Required: one of failed, missing, inactive, stale, degraded, warning, running, paused or ok, worst to best. |
summary |
A line on what it’s doing or how it went. |
busy |
Whether it’s busy now. |
lastRun, lastSuccess, nextRun |
When it last ran, last worked and runs next. |
progress |
How far through it is, from 0 to 1. |
stats |
Figures: each has an id, a label, a value that’s a number or a short string, an optional unit, and an optional kind of duration (seconds), size (bytes, unless it has a unit), timestamp or count, so clients can format it. |
notes |
Short lines of text. |
lists |
Lists of label and value pairs, each with an id, a label and its items. |
actions |
What clients can ask the provider to do: each has an id, a label, an optional confirm question for clients to ask first, and an optional disabled reason it can’t run now. |
An item with no ID, the same ID as an earlier one, or a health outside the list is left out, as is a stat whose value isn’t a number or a string. Each is added to errors, so one bad item doesn’t hide the rest.
An example provider
This script reports one check: how old the newest backup is, from the time a backup tool last touched a file.
#!/usr/bin/env bash
set -euo pipefail
marker="$HOME/.local/state/backup/last-success"
now=$(($(date +%s) * 1000))
if [[ ! -f $marker ]]; then
printf '{"version":1,"updated":%d,"busy":[],"items":[{"id":"backup","label":"Backup","kind":"check","health":"missing","summary":"No backup yet"}],"errors":[]}\n' "$now"
exit 0
fi
last=$(($(stat -c %Y "$marker") * 1000))
age=$(((now - last) / 1000))
health=ok
[[ $age -gt 86400 ]] && health=warning
[[ $age -gt 259200 ]] && health=failed
printf '{"version":1,"updated":%d,"busy":[],"items":[{"id":"backup","label":"Backup","kind":"check","health":"%s","summary":"Newest backup %d hours ago","lastSuccess":%d,"stats":[{"id":"age","label":"Age","value":%d,"kind":"duration"}]}],"errors":[]}\n' \
"$now" "$health" $((age / 3600)) "$last" "$age"
Make it executable, then add it as a provider with no act:
{
"services": {
"providers": [{ "id": "backup", "list": ["/home/me/.local/bin/backup-status"] }]
}
}