ServerKit/docs/REGISTRIES.md

Registries

ServerKit publishes some of its catalogs as standalone repositories that panels read over the network, so entries can ship without a panel release. Three exist today:

Registry	Repo	Bundled in the panel?
Extensions	serverkit-extensions	builtins only; the rest install on demand
Themes	serverkit-themes	17 bundled, gallery adds more
App templates	serverkit-templates	all 106 bundled, registry adds/updates

This document exists because "should X be a registry too?" is a question that otherwise gets re-asked every few months. Most of the time the answer is no.

The test

A catalog earns a registry only when all three hold:

1. It changes faster than the panel releases. If new entries naturally arrive with the feature work that consumes them, a registry buys nothing.
2. It is data, not code. A new entry must work on an existing panel with no code change. If using it requires a new service method, a new job kind, or a new UI surface, it is code wearing a catalog's clothes.
3. Someone outside the release cycle would contribute. If only the maintainers will ever add entries, a directory in this repo is simpler and reviews the same way.

Fail any one, and extraction adds a network dependency, a second release process, and a version-skew surface in exchange for nothing.

The failure mode to avoid

The expensive mistake is extracting a catalog that fails test 2. Panels that have not upgraded keep reading the registry forever. Publish an entry that needs new panel code, and every old panel either ignores it (best case) or shows a broken item it cannot install (worst). At that point the registry needs its own min_panel_version gate — which is exactly why serverkit-extensions has one, and exactly the complexity you do not want unless the catalog earns it.

Why the three qualified

• Extensions are independently versioned code artifacts with permissions and a min_panel_version gate. They are the archetype: third-party authored, released on their own cadence, installed at runtime.
• Themes are pure token maps — data by construction, contributed by people who will never open a panel PR, and worthless if shipping one requires a release.
• App templates are declarative Compose specs. New self-hosted apps appear constantly and each is ~2 KB of YAML that an existing panel already knows how to install. TemplateService has always resolved <repo_url>/index.json + <repo_url>/templates/<id>.yaml; the registry is just the other end of a contract the panel already had.

Note the pattern: bundled and registry are not exclusive. Templates and themes ship inside the panel and have a registry. The bundle is the offline floor — air-gapped installs, fresh installs with no network, and any day GitHub is unreachable — while the registry is the growth path. Only extensions lean on the registry as the primary source, because they are large and optional by nature.

What was assessed and rejected

Catalog	Where	Verdict
Server templates	ServerTemplateService.TEMPLATE_LIBRARY	No. 12 entries, stable, and operators already create their own via create_template() into the DB. The library is a seed, not a catalog.
Notification events	app/notifications/catalog.py	No. Fails test 2 — an event type is only real if panel code emits it. A registry entry with no emitter is a dead row.
AI providers	ai_service.CURATED_PROVIDERS	No. Each entry is bound to a Prompture driver; adding one without the driver produces a provider that cannot connect.
DB tuning settings	db_config_tuner_service.CURATED_SETTINGS	No. Fails test 3 — tuning knobs track the engines the panel supports, and only maintainers will touch them.
Sanitization profiles	models/sanitization_profile.BUILTIN_PROFILES	No. Consumed by code paths that must understand each profile.
Agent survey probes	app/data/survey_probe_catalog.yaml	No. A probe is only meaningful if the agent implements its kind, so it is gated by the agent's release, not the panel's.
Build packs	buildpack_service	No. Not a catalog at all — it generates Dockerfiles and compose from a build plan. That is code.

Open candidate: malware signatures

YARA rules are the one remaining catalog that passes all three tests, and they have no update path today.

YaraScanService.BUILTIN_RULES (16 curated rules, mirrored in yara_rules/webshells.yar) ships inside the panel and changes only when the panel is released. Webshell signatures are the textbook case for out-of-band updates — a new obfuscation family is worth pushing the day it is seen, not the next release.

This matters more than it used to. The container image now builds without ClamAV by default (ARG INSTALL_CLAMAV=false — see the Dockerfile), and ClamAV was the component with a self-updating signature feed via freshclam. In a default container, YARA is the only malware detection, and its rules are frozen at release time.

Operators can already drop custom .yar files into YaraScanService.CUSTOM_RULES_DIR (/var/serverkit/security/yara-custom, real yara CLI required), so the local extension point exists. What is missing is a curated upstream feed that updates itself.

Not built. Noted here so the decision is deliberate rather than forgotten.