// OPENBOX DOCS
Creating an OpenBox Plugin
Build, sandbox, and distribute plugins using standard JSON lifecycle hooks and capability declarations.
OpenBox plugins extend launcher functionality through decoupled lifecycle hooks. Each hook invocation runs in its own subprocess, in a Bubblewrap sandbox (bwrap) when available. A .py entry is driven by plugin_runner_v2.py over a JSON Lines frame; a native executable entry receives the same JSON Lines request directly.
Plugin Manifest (plugin.json)
Every plugin requires a plugin.json manifest placed in its directory under ~/.local/share/openbox-game-launcher/plugins/<plugin-id>/:
{
"id": "play-notifier",
"name": "Play Session Notifier",
"version": "1.0.0",
"api_version": 2,
"min_openbox": "2.0.0",
"description": "Sends local desktop notifications when games start and finish.",
"entry": "plugin.py",
"hooks": [
"before_launch",
"after_session",
"library"
],
"subscriptions": [
"app_shutdown"
]
}
Manifest Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique plugin identifier matching ^[a-z0-9][a-z0-9._-]{1,63}$ (lowercase start, 2-64 characters). This is the install directory name. |
name | string | Display name shown in the Plugins dialog. |
version | string | Non-empty version string (e.g. 1.0.0). |
description | string | Optional short summary of plugin capabilities (500 characters). |
author | string | Optional author name (80 characters) shown with the plugin. |
homepage | string | Optional HTTPS project URL (300 characters). |
entry | string | Entry point inside the package (defaults to plugin.py). A .py file runs through plugin_runner_v2.py; any other executable file runs directly. It must resolve inside the package, with no symlinks or ... |
hooks | array | Subscribed hooks: the six base hooks (before_launch, after_session, library, command, library_source, events) plus the six capability hooks (storefront, metadata, media, stats, emulator, discovery). |
api_version | integer | Required. Must be 2 in 3.0. A missing value or 1 fails with PLUGIN_API_RETIRED. Version 2 uses the JSON Lines runner and unlocks min_openbox, subscriptions, and the versioned read-only host services (library.query, media.search). |
min_openbox | string | v2 only: oldest OpenBox release that may serve the plugin; older hosts refuse it at load. |
subscriptions | array | v2 only: named events the runner delivers, on top of the base events hook. |
commands | array | Up to 32 {id, label, description?} entries, exposed in the command palette under the > prefix. |
permissions | array | Declared permissions; the only permission is network, granted by the user in the Plugins manager. |
settings | object | JSON Schema subset for per-plugin settings; the Plugins manager and Settings > Plugins render a form and inject stored values into hook payloads. |
capabilities | object | Capability declarations (1.18.0+). Each requires its matching hook and is what makes a plugin act like a built-in source. |
messages | object | Localized notification templates (1.18.0+), resolved against the active locale. |
Capabilities
A capability is additive on top of the base hooks and is accepted only when the plugin also declares its implementing hook:
{
"id": "vendor.switch-store",
"name": "Vendor Switch Store",
"version": "1.0.0",
"api_version": 2,
"hooks": ["storefront", "metadata"],
"permissions": ["network"],
"capabilities": {
"storefront": {"id": "vendor.store", "name": "Vendor store"},
"metadata": {"id": "vendor.metadata", "name": "Vendor metadata", "platform": "Nintendo Switch"}
}
}
| Capability | Hook | Extra fields | Timeout |
|---|---|---|---|
storefront | storefront | optional platform | 30 s |
metadata | metadata | optional platform | 15 s |
media | media | optional media_kinds (default ["cover", "background"]) | 15 s |
stats | stats | — | 15 s |
emulator_settings | emulator | list of {emulator_id, label, schema, scopes} | 10 s |
discovery | discovery | — | 10 s |
Capability hooks receive three extra payload keys: plugin_data (the bounded 1 MiB data bag), settings (non-secret values), and credentials (the capability credential store). They may return data, notification, and service_requests. A capability hook can ask the host for up to eight read-only services in one round — library.query, achievements, profile, activity, leaderboards, catalog.search, metadata.search, media.search — and is invoked once more with service_results. There is no separate services hook.
Storefront, metadata, media, and stats capabilities require a declared and granted network permission; the host refuses to call them otherwise. See Plugin hooks for each payload and result shape, and Plugin manifest for validation rules.
Localized notifications
Declare message templates and reference them from any hook result:
"messages": {
"sync_done": {"en": "{count} games synced", "de": "{count} Spiele synchronisiert"}
}
def command(payload):
return {"notification": {"level": "success", "key": "sync_done", "params": {"count": len(payload["library"])}}}
Supported locales are en, es, de, fr, and pt. The host resolves the active locale, then English, then the raw key; each template is capped at 500 characters and the resolved message at 2,000.
Hook Lifecycles & JSON Protocol
OpenBox runs each hook as a child process. For a .py entry it starts python3 -B plugin_runner_v2.py <entry> (wrapped in bwrap when available) and sends one JSON Lines {"type":"invoke", "hook": ..., "payload": ...} frame. For a native entry it executes the entry directly and sends the same frame. The runner calls the function named after the hook: def library(payload), def before_launch(payload), def after_session(payload), def command(payload), def library_source(payload), def events(payload), def storefront(payload), def metadata(payload), def media(payload), def stats(payload), def emulator(payload), or def discovery(payload). If the module does not define the hook function, the payload passes through unchanged.
Supported Hooks
before_launch: Invoked at launch, after profile and archive resolution. Python fallback only in 3.0.- Input Payload:
{"game": {"id": 1, "name": "Chrono Trigger", "platform": "SNES", "path": "/roms/snes/ct.sfc", ...}, "args": ["retroarch", "-L", "core.so", "/roms/snes/ct.sfc"], "cwd": "/roms/snes"} - Output Result:
{"args": [...], "cwd": "..."}to rewrite the launch argv/working directory, or{"cancel": true, "error": "why"}to abort the launch with that message. Structurally invalid output (empty argv, nonexistentcwd, or a different executable inargs[0]) raises a launch validation error.
- Input Payload:
after_session: Dispatched when a game process exits.- Input Payload: the session record itself,
{"game": "Chrono Trigger", "started": "...", "seconds": 1800, "exit_code": 0, ...} - Output Result: any dict; the result is discarded. Exceptions are caught by the runner, so a failing plugin never breaks session bookkeeping.
- Input Payload: the session record itself,
library: Dispatched on library reads (cached 30 seconds, invalidated on state changes).- Input Payload:
{"games": [...]}— the full public game projection. - Output Result:
{"games": [...]}— a dict whosegameslist has the same length as the input, every element a dict. Anything else is ignored and the pre-plugin list wins.
- Input Payload:
command: Invoked from the command palette (>prefix) orPOST /api/v2/plugins/commandfor a manifest-declared command.- Input Payload:
{"command": "<command id>", "library": [...]}— the library summary is bounded to 500 entries with onlygame_id,name,platform,progress,favorite, andplaytime_seconds. - Output Result: any dict; may include
{"notification": {"level": "info" | "success" | "warning" | "error", "message": "..."}}(or akey/paramsreference) to show a UI notification. Hook errors are surfaced to the caller.
- Input Payload:
library_source: Runs on every library state build, making the plugin a library importer.- Input Payload:
{"api_version": 2}(plussettingswhen the manifest declares a settings schema). - Output Result:
{"games": [...]}— a bare list or any other shape is rejected with a warning. Entries are namespaced asplugin:<plugin_id>:<their_id>and shown with a source badge; disabling or removing the plugin drops its games.
- Input Payload:
events: Fan-out for lifecycle events. The Rust server emitsapp_startupandapp_shutdown; the Python fallback also emitsscan_finished,playtime_milestone,game_added,game_removed, andgame_updated.- Input Payload:
{"event": "<name>", ...}with a small bounded payload (e.g.game_addedcarriesgame_ids, up to 500;game_updatedcarrieschanges, up to 100). - Output Result: any dict; failures never break the host operation.
- Input Payload:
- Capability hooks:
storefront,metadata,media,stats,emulator, anddiscovery. Each has a purpose-built payload and result, documented in Plugin hooks. A capability hook is invoked directly (not chained) and gets the data bag, capability settings, and credentials.
Minimal Python Plugin (plugin.py)
def before_launch(payload):
# Log to stderr (last 400 bytes are captured in the diagnostic log on failure)
game = payload.get("game", {})
print(f"[Notifier] Starting game: {game.get('name')}", file=sys.stderr)
# Optionally rewrite the launch argv (args[0] must stay the same executable).
# Use an option supported by the launched game or emulator, not an OpenBox
# window flag.
payload["args"].append("--game-specific-option")
return payload
def after_session(session):
print(f"[Notifier] Finished {session.get('game')} (played {session.get('seconds')}s)", file=sys.stderr)
return session
def library(payload):
for game in payload.get("games", []):
game["notes"] = (game.get("notes") or "") + " [plugin]"
return payload
The entry module is loaded by the runner, not executed directly, so it does not need a shebang or executable permissions.
A capability plugin follows the same shape, with the capability declared in the manifest:
def discovery(payload):
# On the first call ask the host for a bounded library slice; the host
# re-invokes the hook once with `service_results` filled in.
results = payload.get("service_results")
if results is None:
return {"service_requests": [{"id": "lib", "action": "library.query", "params": {"limit": 10}}]}
games = results.get("lib", {}).get("games", [])
return {
"lists": [
{"id": "short", "name": "Short games", "game_ids": [row["game_id"] for row in games[:5]]},
]
}
def stats(payload):
# payload["games"] holds up to 500 {game_id, name, platform, ...} rows.
return {
"games": [
{
"game_id": row["game_id"],
"playtime_seconds": 3600,
"last_played": "2026-10-19T12:00:00",
"achievements": {"source": "vendor", "name": "Vendor", "earned": 3, "total": 10},
}
for row in payload["games"]
]
}
Bubblewrap Sandboxing
OpenBox isolates plugin execution using Bubblewrap (bwrap) when available on Linux systems:
- Read-only root filesystem bind (
--ro-bind / /) - Isolated process namespace (
--unshare-all) - Private empty
tmpfsmounts for/home,/tmp,/run,/mnt,/media - Network isolation (disabled by default;
--share-netonly after anetworkgrant)
When the sandbox cannot be created, enabled plugins are skipped with a warning. To run trusted local plugins without the sandbox, either trust the plugin in the Plugins manager (Trust and run — the grant is bound to the package's SHA-256, so updates re-prompt) or set OPENBOX_ALLOW_UNSANDBOXED_PLUGINS=1 in the process environment (not .env). To disable all plugin execution for troubleshooting, launch OpenBox with OPENBOX_SAFE_MODE=1.
Windows has no bwrap, so plugin hooks cannot be isolated there: enabled plugins are skipped with the same warning until you trust them one by one in the Plugins manager or set OPENBOX_ALLOW_UNSANDBOXED_PLUGINS=1. The runner then executes as an ordinary subprocess with your own user's access to the filesystem and network, so trust it only for plugin code you have read.
Installing & Testing
- Create directory
~/.local/share/openbox-game-launcher/plugins/my-plugin/on Linux,~/Library/Application Support/openbox-game-launcher/plugins/my-plugin/on macOS, or%LOCALAPPDATA%\openbox-game-launcher\plugins\my-plugin\on Windows. - Add
plugin.jsonandplugin.py. - Open OpenBox → Tools → Plugins.
- Enable your plugin in the list. Trust it if the host reports the sandbox is unavailable, and grant
networkif it declares that permission. - If the manifest declares
settings, check the form under Settings → Plugins; values are validated on save and passed to the hook aspayload["settings"]. - Check the diagnostic log (
openbox.logbeside that data directory) for plugin warnings (skipped plugins, timeouts, oversized output, and the last 400 bytes of stderr on a nonzero exit). Settings → Copy diagnostic log copies a redacted summary to the clipboard. - Use Reinstall in the Plugins manager to repair an installed package without losing settings, stats, or trust.