// OPENBOX DOCS
Plugins
Build trusted local plugins with the documented manifest, hook, and capability contract.
Plugins are local packages that extend OpenBoxGL through documented hooks. A v2 entry may be a Python file or a native executable. They run as separate processes with a JSON Lines protocol, so a plugin that crashes or misbehaves cannot take down the library.
Quick facts
- Plugin API v1 was removed in 3.0. Every manifest must declare
"api_version": 2; a missing value or1fails withPLUGIN_API_RETIRED. - A plugin manifest (
plugin.json) requiresid,name, andversion. IDs match^[a-z0-9][a-z0-9._-]{1,63}$;data,credentials, andplugins-state.jsonare reserved. - The implementation entry defaults to
plugin.py; explicit entries such asmain.pyare supported. A.pyentry runs throughplugin_runner_v2.py; any other executable entry runs directly. - Base hooks are
library,before_launch,after_session,command,library_source, andevents(the last three added in v1.14.0). A declared base hook outside this set is rejected. - Capability hooks (1.18.0) are
storefront,metadata,media,stats,emulator, anddiscovery. Each is declared throughcapabilities, and a capability without its hook is a manifest error. There is no standaloneserviceshook; a capability hook may returnservice_requestsinstead. - The runner exchanges one JSON Lines frame per invocation, chains base hooks in sorted (alphabetical by directory) order, caps input at 2 MiB and output at 4 MiB, and stops a plugin after its hook timeout (5 seconds for base hooks; 30 s storefront, 15 s metadata/media/stats, 10 s emulator/discovery). Each hook invocation starts a fresh process.
- The plugin environment is cleaned before execution:
PYTHONPATH,PYTHONHOME,LD_PRELOAD, andLD_LIBRARY_PATHare removed andPYTHONNOUSERSITE=1is set. - Capability hooks also receive a bounded data bag, non-secret settings, and capability credentials. Backups exclude the credential store and blank password-format settings.
- Plugins are local code. Review them before installation. Safe mode (
OPENBOX_SAFE_MODE=1) skips the lifecycle hooks (library,before_launch,after_session,library_source,events) and the webhook dispatcher, but not the capability hooks — an explicit storefront, metadata, media, stats, emulator-settings, or discovery call still invokes that plugin's hook. Failed installations roll back to the previous version.
Reference pages
- Plugin API overview, trust boundary and lifecycle
- Plugin manifest reference, fields, ID validation, entry selection, capabilities and messages
- Plugin hooks reference, the payloads, service requests, and response rules
- Plugin processes and errors, protocol limits, timeouts, safe mode, rollback
- Plugin catalog reference, bundled catalog entries and installation
Install locations
Plugins live in plugins/ inside the data directory. Installation accepts a directory or a ZIP package; the ZIP is extracted with the same safe extraction rules as game archives (no symlinks, no .. paths, bounded sizes). State such as disabled plugins is kept in plugins-state.json next to the directory. Per-plugin data and credentials live under plugins/data/ and plugins/credentials/ with mode 0600, and cached stats live under plugin-stats/.
See also
- Configuration for
OPENBOX_SAFE_MODEand the data directory. - Data and recovery for the library state plugins transform.
- API local administrator for the install/toggle/remove routes.