// OPENBOX DOCS
Plugin API overview
Trust boundary, the local plugin lifecycle, and capability services.
Plugins are optional local packages that observe or extend OpenBoxGL. A v2 entry may be a Python file or a native executable. They are untrusted-by-default third-party code: review a package before installing it, and use safe mode to disable lifecycle hooks and webhooks when something misbehaves. Plugin API v1 was removed in 3.0; every manifest must declare "api_version": 2.
Trust boundary
- On Linux, each hook runs inside a bubblewrap OS sandbox when
bwrapis available: every namespace is unshared (no network access), the host root is mounted read-only, and/home,/tmp,/run,/mnt, and/mediaare replaced with empty filesystems. The plugin sees only its own package directory (read-only) and the JSON hook payload on stdin — never your data directory or home folder. - If the sandbox cannot be created, the plugin is skipped rather than run unsandboxed, unless you trust the plugin or set
OPENBOX_ALLOW_UNSANDBOXED_PLUGINS=1. Two paths exist: per-plugin "Trust and run" in the Plugins manager, which binds the grant to the installed package's SHA-256 (any update that changes the package invalidates the grant and re-prompts), or the legacy operator-wideOPENBOX_ALLOW_UNSANDBOXED_PLUGINS=1escape hatch for trusted local code. Reserve unsandboxed execution for plugin code you have read and audited: without the sandbox, the plugin runs as a plain child process with your user privileges and can read and modify files in your data directory and under your account, not only library entries. On Windowsbwrapdoes not exist, so the same per-plugin trust prompt is the only gate. - In both modes the plugin environment is scrubbed before launch:
PYTHONPATH,PYTHONHOME,LD_PRELOAD, andLD_LIBRARY_PATHare removed,PYTHONNOUSERSITE=1is set, and any variable whose name containsTOKEN,PASSWORD,SECRET, orAPI_KEY(case-insensitive) — or starts withOPENBOX_,RETROACHIEVEMENTS_,EMUMOVIES_,GITHUB_,RA_,IGDB_, orGAMEYFIN_— is stripped, so plugins cannot read tokens, secrets, or host state out of the environment. - Install only packages you wrote or audited. The bundled catalog is documentation-oriented; installing from it still runs downloaded code.
Lifecycle
- Install (
/api/v2/plugins/install): a directory or ZIP package is staged, validated, and moved intoplugins/<id>/. Updates replace the previous version atomically; a failed install or update restores the previous version. - Enable/disable (
/api/v2/plugins/toggle): disabled plugin ids persist inplugins-state.json; disabled plugins are skipped by every hook. Disabling also deletes the games the plugin imported and stops its cached stats from merging, while keeping its stored settings, trust, grants, data, and credentials. - Run: on each hook event, enabled plugins that declare the hook execute in sorted (alphabetical) directory order, each as a separate process.
- Remove (
/api/v2/plugins/remove): the package moves toplugins/.removed/<id>-<timestamp>(recoverable), imported games are deleted, and its disabled state, trust grant, permission grants, settings, data bag, credentials, and stats cache are cleared, so a reinstall comes back enabled and untrusted. - Repair/reinstall (
POST /api/v2/plugins/repair, 1.18.0+): reinstalls an installed plugin from its catalog entry, or from its recorded local package when the catalog has no entry (the recorded SHA-256 is re-verified). Settings and cached stats are preserved, and the trust record is kept but re-evaluated against the new package checksum: a reinstall whose bytes differ leaves the plugin untrusted and asks for approval again. - Trust (
GET/POST /api/v2/plugins/trust, 1.14.0+): on a host where the bubblewrap sandbox cannot be created, a plugin does nothing until you grant per-plugin trust in the Plugins manager. The grant is bound to the installed package's SHA-256, so any update that changes the package invalidates it and re-prompts. There is deliberately no global "trust everything" switch;OPENBOX_ALLOW_UNSANDBOXED_PLUGINS=1remains the operator-level override. - Permissions (
POST /api/v2/plugins/permissions, 1.14.0+): declared permissions are denied by default. The only permission isnetwork; granting it adds--share-netto the plugin's sandbox argv, and without the grant the plugin keeps the no-network sandbox. A grant can never exceed the manifest declaration. - Settings (
GET/POST /api/v2/plugins/settings, 1.14.0+): a manifestsettingsJSON Schema subset renders a form under Settings > Plugins; validated values are stored per plugin and delivered to the hook aspayload["settings"]. - Data and credentials (1.18.0+):
GET/POST /api/v2/plugins/datareads or shallow-merges the bounded data bag;GET/POST /api/v2/plugins/credentialswrites capability credentials and only ever returns key names and presence flags.
Hook execution points
| Hook | When | Effect on result |
|---|---|---|
library | Every /api/v2/library read (cached for 30 seconds), skipped in safe mode. Python fallback only in 3.0. | May rewrite the games list; the response uses the last plugin's output when it is a dict with a games list of the same length |
before_launch | At launch, after profile/archive resolution, skipped in safe mode. Python fallback only in 3.0. | May rewrite args/cwd or cancel with {"cancel": true, "error": "..."}; structurally invalid output is discarded with a warning and the original launch command is used |
after_session | After a session ends (history recorded, plugins run unless safe mode). Python fallback only in 3.0. | Ignored (return value discarded) |
command | When a palette command is invoked (1.14.0+) | Returns an optional notification to show; unlike the chained hooks, its errors surface to the caller |
library_source | On every library read, for manifests declaring it (1.14.0+). Python fallback only in 3.0. | Contributes imported games, namespaced plugin:<plugin_id>:<id> and merged into the public library |
events | On lifecycle events. The Rust server emits app_startup and app_shutdown; the Python fallback also emits scan_finished, playtime_milestone, game_added, game_removed, and game_updated (1.14.0+) | Result discarded; a failure is logged and never breaks the emitting operation |
storefront, metadata, media, stats, emulator, discovery | Only for plugins that declare the matching capability (1.18.0+) | Provides source-style data; see Hooks |
Capability services
A capability hook may return service_requests — at most 8, each {id, action, params} — and the host executes them against a read-only, bounded allowlist:
| Service | Returns | Limits |
|---|---|---|
library.query | Game rows visible in the UI | 500 games, no filesystem paths |
achievements | Per-game achievement sources and items | 100 games, 500 items |
profile | Library and achievement profile summary | bounded object |
activity | Recent play activity | 100 rows |
leaderboards | Achievement leaderboard rows | 100 rows |
catalog.search | Catalog entries matching a query | 20 rows (10 by default) |
metadata.search | Metadata candidates for one game | 10 rows (5 by default) |
media.search | Media candidates for one game | 20 rows (10 by default) |
The host then re-invokes the same hook once with service_results keyed by request id. That second round is final: a second service_requests list is ignored with a logged warning. Service payloads never carry path-like keys (path, save_paths, media_root, and similar), and every request is validated; a failing service returns {"error": "..."} for that request instead of failing the hook.
There is no standalone services hook. Declaring one is rejected, and service_requests from a non-capability hook is discarded with "service_requests are only available to capability hooks."
Safe mode
OPENBOX_SAFE_MODE=1 (any non-empty value) in the process environment skips the lifecycle hooks: library, before_launch, after_session, the library_source merge, and events emission, and it disables the webhook dispatcher. Palette command runs are refused, and the setting is exposed to the UI as settings.safe_mode. It is the first thing to try when a plugin causes launch or library failures. Note that an explicit capability action (storefront catalog or import, a metadata/media search, a stats refresh, or plugin discovery lists) still invokes that plugin's hook; disable the plugin itself to stop those.
Limits and failure behavior
- One JSON object per invocation over stdin/stdout.
- Input payload capped at 2 MiB; output capped at 4 MiB for
api_version: 2. Oversized output is ignored with a warning. - Per-hook timeout: 5 seconds for base hooks, 30 seconds for
storefront, 15 seconds formetadata/media/stats, and 10 seconds foremulator/discovery. A timeout, crash, or invalid JSON logs a warning and the plugin's result is skipped (the previous result passes through). Palettecommandruns are the exception: a hook error there is surfaced to the API caller as a400. - A nonzero exit is logged with the last 400 bytes of stderr.
- The plugin environment is cleaned:
PYTHONPATH,PYTHONHOME,LD_PRELOAD,LD_LIBRARY_PATHremoved,PYTHONNOUSERSITE=1. - The data bag must stay at or under 1 MiB and four levels deep; a patch that breaks either bound writes nothing.
Plugin v2 routes
GET /api/v2/plugins/commands— manifest-declared commands from enabled, valid plugins;POST /api/v2/plugins/commandwith{plugin_id, command}runs thecommandhook.GET /api/v2/plugins/trust?id=<id>/POST /api/v2/plugins/trustwith{id, trusted}— per-plugin sandbox-bypass trust (checksum-bound, updates re-prompt).POST /api/v2/plugins/permissionswith{id, permissions}— grant declared permissions (currentlynetworkonly).GET /api/v2/plugins/settings?id=<id>/POST /api/v2/plugins/settingswith{id, values, clear_secrets?}— schema, redacted values, validated save.GET/POST /api/v2/plugins/datawith{id, values}— read or shallow-merge the bounded data bag.GET/POST /api/v2/plugins/credentials— credential key summary, or write{id, values, clear}; values never travel back.POST /api/v2/plugins/repairwith{id}— reinstall without touching settings or stats; the trust record is kept but re-evaluated against the new package checksum, so changed bytes ask for approval again.GET /api/v2/plugins/catalog— catalog entries enriched withinstalled,installed_version,update_available, plusauthorandhomepage;sandboxis a top-level field of the response.GET /api/v2/plugin-stats/POST /api/v2/plugin-stats/refreshwith{plugin_id | plugin_ids}— cached stats source summaries, or refresh up to 64 sources.POST /api/v2/storefronts/plugin/catalog/POST /api/v2/storefronts/plugin/importwith{plugin_id, installed_only?, uninstalled_only?}— the shared storefront catalog and import path for plugin storefronts.