// OPENBOX DOCS
Plugin processes and errors reference
Protocol limits, per-hook timeouts, safe mode, and rollback.
Every plugin invocation runs in a fresh child process with a JSON Lines frame on stdin/stdout. Plugin API v1 and plugin_runner.py were removed in 3.0; every manifest must declare "api_version": 2 or it fails with PLUGIN_API_RETIRED. This page documents the exact limits and failure handling.
Protocol (v2)
- A
.pyentry is started throughpython3 -B plugin_runner_v2.py <entry>; a native executable entry is started directly. The host writes one{"type":"invoke", "hook": ..., "payload": ...}frame and reads aresult,error, orcancelledframe. - A plugin whose module lacks the hook function gets the input payload and echoes it back.
- A plugin whose return value is not a dict falls back to the input payload.
- Capability hooks get one optional extra round for
service_requests: the host runs at most 8 read-only services and re-invokes the same hook once withservice_results. A second request list is dropped with a warning. - Host services are versioned, read-only descriptors (
library.query,media.search) requested through the runner rather than a re-invoked hook. - There is no persistent runner process; each hook call starts a new process. A timeout kills that process.
Limits
| Limit | Value | Behavior when exceeded |
|---|---|---|
| Input payload | 2 MiB (MAX_PLUGIN_PAYLOAD) | The plugin is skipped with "Payload is too large for plugin execution." |
| Output | 4 MiB (v2 only) | Output beyond the cap is ignored: "Plugin output exceeded the payload limit." |
| Execution time, base hooks | 5 seconds | The process is killed; a warning is logged and the plugin's result is skipped |
Execution time, storefront | 30 seconds | Above |
Execution time, metadata / media / stats | 15 seconds | Above |
Execution time, emulator / discovery | 10 seconds | Above |
| stderr kept | last 400 bytes | Included in the failure warning |
| Data bag | 1 MiB, 4 levels deep | A patch that breaks either bound raises and writes nothing |
| Service requests | 8 per hook, one round | More than 8 raises "service_requests must be a list of at most 8 requests."; a second round is ignored |
| Storefront paging | 20 pages, 2,000 entries | Paging stops; a repeated cursor raises "Plugin storefront pagination repeated a cursor." |
| Storefront entry | id up to 160, text up to 300, URL up to 2,000 | Longer values are truncated or the entry is skipped |
| Credentials | 128 keys, 4,096 characters per value | A write beyond 128 keys or a longer value raises; malformed stored entries are ignored when read |
The payload check happens before spawn for input; the output check happens after the process exits.
Environment
The child environment is cleaned before execution:
- Removed:
PYTHONPATH,PYTHONHOME,LD_PRELOAD,LD_LIBRARY_PATH - Added:
PYTHONNOUSERSITE=1 - Stripped: any variable whose name contains
TOKEN,PASSWORD,SECRET, orAPI_KEY(case-insensitive), or starts withOPENBOX_,RETROACHIEVEMENTS_,EMUMOVIES_,GITHUB_,RA_,IGDB_, orGAMEYFIN_ start_new_session=Trueso the plugin runs in its own process group (and can be killed without touching the parent)
Failure handling
| Failure | Consequence |
|---|---|
| Nonzero exit | Warning "Plugin exited with status <code>: <stderr tail>" — the message does not name the plugin; payload passes through unchanged |
Timeout (subprocess.TimeoutExpired) | Warning; payload passes through |
| Invalid JSON on stdout | Warning "Plugin returned invalid JSON."; payload passes through |
| Non-dict JSON | Warning "Plugin output must be a JSON object."; result ignored; payload passes through |
| Exception inside the plugin | The child exits nonzero; handled as above. Plugin exceptions can never raise inside the OpenBoxGL process |
Spawn error (OSError) | Warning; payload passes through |
A plugin therefore cannot break a launch or a library read by crashing: worst case its changes are dropped and a warning is logged. Exceptions:
- A non-dict
before_launchreturn falls back to the input payload (the runner echoes it), and structurally invalidargs/cwdare discarded with a warning while the host launches with the original command; only{"cancel": true}aborts the launch. commandhook errors (bad JSON, non-object, oversized output, nonzero exit, timeout) are surfaced to thePOST /api/v2/plugins/commandcaller as a400. The route also refuses a disabled plugin or safe mode with"Plugin is disabled."- Capability hooks follow their consumer: a
storefrontfailure or malformed page raises for the catalog/import action, ametadataormediafailure yields an empty candidate list so other providers still run, astatsfailure raises for the refresh, and anemulatorsection that returns bad args/env is skipped with a warning while the launch continues. A failing optionaldiscoveryplugin is skipped instead of breaking the Discovery Center. - A returned
credentialskey is removed and logged: hooks cannot write the credential store.
Safe mode
With OPENBOX_SAFE_MODE set in the environment:
run_pluginsis never called forlibrary,before_launch, orafter_session; thelibrary_sourcemerge andeventsemission are skipped as well.- The webhook dispatcher is not created (
get_webhook_dispatcherreturns None). settings.safe_modereports true to the UI.POST /api/v2/plugins/commandrefuses to run ("Plugin is disabled.").- Capability hooks are not globally gated. An explicit storefront catalog/import, metadata or media search, stats refresh, or plugin discovery call still invokes the plugin's sandboxed hook; disable the plugin to stop those.
Safe mode is a diagnosis tool: enable it, confirm the problem disappears, then remove or fix the offending plugin and restart normally.
Install and update rollback
install_plugin stages the new package and swaps it in:
- Existing version (if any) moves to
plugins/.backups/<id>-<timestamp>. - The staged copy is moved to
plugins/<id>. - On any failure, the backup is moved back if the destination is missing; the staging directory is always cleaned up.
- On success, the backup is deleted.
Both the copy failure and the swap failure paths are covered by tests: a disk-full error during staging and a failed Path.replace during the swap both leave the previous version installed and enabled. Reinstalling after removal clears disabled state, so the plugin comes back enabled.
Repair, disable, and remove
POST /api/v2/plugins/repairwith{id}reinstalls the package from the catalog entry, or from the recorded local package when the catalog has none. The recorded SHA-256 is re-verified first; a changed local package raises"The recorded local plugin package changed; reinstall it manually."Settings, stats cache, and grants survive the reinstall, 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.- Disabling a plugin keeps its records (settings, trust, permissions, data, credentials, stats cache) but deletes the games it imported and stops its cached stats from merging.
- Removing a plugin moves the package to
plugins/.removed/<id>-<timestamp>and deletes the plugin's settings, trust, permission grants, data bag, credentials, and stats cache, along with its imported games. A reinstall after removal comes back enabled, untrusted, and without approvals.
Related
- Plugin hooks reference for payload shapes
- Plugin manifest reference for what installs validate
- API local administrator for the install/toggle/remove routes