// OPENBOX DOCS

Plugin catalog reference

Bundled catalog entries and local installation behavior.

The plugin catalog is the curated list of community plugins OpenBoxGL knows about. It is bundled with the application and refreshed from a commit-pinned repository URL when the network is available.

Catalog sources

Source	Path / URL	Timeout / cap	Fallback
Remote	The pinned `plugins/catalog.json` commit on the OpenBoxGL repository	20 s, 4 MiB, plus a pinned SHA-256 check on the response	Bundled local catalog
Local	`plugins/catalog.json` next to the application	none	`[]`

GET /api/plugins/catalog tries the remote catalog first and falls back to the bundled file on any network, checksum, or parse failure, so the catalog always returns something valid. GET /api/v2/plugins/catalog (1.14.0+) additionally enriches every entry with installed, installed_version, and update_available, and reports the current sandbox status as a top-level response field.

The newer GET /api/v2/plugins/catalog returns the same entries enriched with installed, installed_version, and update_available for each entry, plus a top-level sandbox field describing the host sandbox status (the enrichment is per-entry, not attached to sandbox).

Bundled entries

The current bundled catalog (plugins/catalog.json) contains two documentation examples, both local_only:

id	name	hooks	url	notes
`openbox.library-stats`	Library Stats Hook	`after_session`	(empty)	`local_only: true` example
`openbox.hello-palette`	Hello Palette	`command`	(empty)	`local_only: true` example declaring one palette command

Entry fields

Field	Meaning
`id`	Plugin id, must match the manifest pattern (`^[a-z0-9][a-z0-9._-]{1,63}$`)
`name`	Display name
`version`	Version string
`description`	What the plugin does
`url`	Download URL for the plugin package (ZIP)
`hooks`	Declared hooks
`sha256`	Optional SHA-256 of the package; verified during download when present
`local_only`	When true, the entry is documentation-only: installing it raises `400` `"This catalog entry is documentation-only. Install local plugin packages manually."`

Installing from the catalog

POST /api/plugins/catalog/install with {"id": "<catalog id>"}:

Fetches the current catalog.
Looks up the id; unknown ids raise 400 "Unknown catalog plugin."
Downloads the package into a temporary directory with a 128 MiB cap, 120-second timeout, and SHA-256 verification when the entry provides sha256.
Installs it with the normal plugin installer (safe extraction, staging, rollback).

The plugin is then listed by GET /api/plugins and runs its declared hooks.

Security notes

Catalog entries are still third-party code. The catalog URL and sha256 only ensure the bytes you download match what the catalog advertises; they do not make the plugin trustworthy. Review plugin.py after install (it lives in plugins/<id>/).
The remote catalog is fetched over HTTPS from the OpenBoxGL repository, so the trust chain is the repository's.
If the network is unavailable or the remote catalog is unreachable, installs fall back to the bundled catalog (which has no downloadable entries today), and manual ZIP/directory installs remain the reliable path.

Plugin manifest reference
Plugin processes and errors
API local administrator for the catalog routes