Operations

Operations

Checking on a running server, and fixing the usual problems. Every field of every response is in Endpoints.

Is it working?

curl -s localhost:8000/health | jq

The top of the answer is the summary:

{
  "status": "ok",
  "generation": 3,
  "built": "2026-09-17T11:02:41Z",
  "skills": 90,
  "prompts": 4,
  "libraries": { … },
  "plugins": { … },
  "fetches": { … }
}

status is always ok and the HTTP status always 200: it means the process is serving, not that everything loaded. To find out what did not, look in the three maps below it:

Map	One entry per	Look here for
libraries	library in the config	what a client sees, and what a marketplace left out
plugins	plugin, declared or from a marketplace	why something is missing — this is usually where
fetches	repository, folder or path downloaded	whether a remote is reachable

Each plugin and fetch has a status:

Status	Means	Served
ok	the last build worked	that build
stale	a later refresh failed	the last good copy, unchanged
failed	it never built	nothing

stale fixes itself when the remote comes back. failed needs the error next to it read.

Something is missing

Find it in /health and read what sits beside it.

• A plugin is failed. Its error says why. Usually its fetch failed — wrong credentials, a remote that is down — or its folder is not in the repository at that ref, or its plugin.json is not valid JSON.
• A library has an error. Its marketplace could not be read, or it names a plugin nothing declares. The rest of the library still serves.
• A plugin has skipped entries. Each has a path and a reason: usually a skill whose name does not match its folder, or two skills or prompts with one name.
• A library has skipped entries. Marketplace entries this server does not install — npm, archive, command and strict: false entries.
• A library has conflicts. Two of its plugins serve the same address, and the later one is left out of that library. Only a config change clears it. See Libraries.

Picking up changes

A source with a refresh: interval is checked on that interval, and only rebuilt when something actually moved. A source without one is read at boot and left alone.

To rebuild everything now:

curl -sX POST localhost:8000/reindex | jq .rebuilt

The answer is /health plus rebuilt, the fetches it rebuilt.

Clients may not notice straight away. A client with a session is told on its next request. A client without one relies on the listing's cache lifetime, which is the shortest refresh: in the config — so if no source has a refresh:, those clients are never told. Give at least one source a refresh: if that matters.

Probes

Probe the HTTP status, alert on the body. A probe that fails when a fetch fails turns one unreachable remote into a restart loop, and a restart does not bring a remote back. Deployment has probe settings.

Restarts are slow

The server saves what it built in index.json in the cache directory, and a restart with that file is near-instant. It re-downloads everything when:

• the cache directory is not writable by uid 65534 — the log says so;
• the config changed since the file was written;
• the server was upgraded to a version that records things differently.

The last two are one slow boot, then fast again. The cache is always safe to delete; it costs one full download.

A WebDAV server stops answering

A cache: live source checks each file as it is read. If the server stops answering, one read waits a short timeout, then the source is served from its local copy for the next 30 seconds and shows cooling: true in /health. It recovers on its own once the server answers.

---

Home · Deployment · Endpoints · Sources