// 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

FieldTypeDescription
idstringUnique plugin identifier matching ^[a-z0-9][a-z0-9._-]{1,63}$ (lowercase start, 2-64 characters). This is the install directory name.
namestringDisplay name shown in the Plugins dialog.
versionstringNon-empty version string (e.g. 1.0.0).
descriptionstringOptional short summary of plugin capabilities (500 characters).
authorstringOptional author name (80 characters) shown with the plugin.
homepagestringOptional HTTPS project URL (300 characters).
entrystringEntry 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 ...
hooksarraySubscribed 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_versionintegerRequired. 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_openboxstringv2 only: oldest OpenBox release that may serve the plugin; older hosts refuse it at load.
subscriptionsarrayv2 only: named events the runner delivers, on top of the base events hook.
commandsarrayUp to 32 {id, label, description?} entries, exposed in the command palette under the > prefix.
permissionsarrayDeclared permissions; the only permission is network, granted by the user in the Plugins manager.
settingsobjectJSON Schema subset for per-plugin settings; the Plugins manager and Settings > Plugins render a form and inject stored values into hook payloads.
capabilitiesobjectCapability declarations (1.18.0+). Each requires its matching hook and is what makes a plugin act like a built-in source.
messagesobjectLocalized 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"}
  }
}
CapabilityHookExtra fieldsTimeout
storefrontstorefrontoptional platform30 s
metadatametadataoptional platform15 s
mediamediaoptional media_kinds (default ["cover", "background"])15 s
statsstats—15 s
emulator_settingsemulatorlist of {emulator_id, label, schema, scopes}10 s
discoverydiscovery—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

  1. 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, nonexistent cwd, or a different executable in args[0]) raises a launch validation error.
  2. 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.
  3. 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 whose games list has the same length as the input, every element a dict. Anything else is ignored and the pre-plugin list wins.
  4. command: Invoked from the command palette (> prefix) or POST /api/v2/plugins/command for a manifest-declared command.
    • Input Payload: {"command": "<command id>", "library": [...]} — the library summary is bounded to 500 entries with only game_id, name, platform, progress, favorite, and playtime_seconds.
    • Output Result: any dict; may include {"notification": {"level": "info" | "success" | "warning" | "error", "message": "..."}} (or a key/params reference) to show a UI notification. Hook errors are surfaced to the caller.
  5. library_source: Runs on every library state build, making the plugin a library importer.
    • Input Payload: {"api_version": 2} (plus settings when the manifest declares a settings schema).
    • Output Result: {"games": [...]} — a bare list or any other shape is rejected with a warning. Entries are namespaced as plugin:<plugin_id>:<their_id> and shown with a source badge; disabling or removing the plugin drops its games.
  6. events: Fan-out for 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.
    • Input Payload: {"event": "<name>", ...} with a small bounded payload (e.g. game_added carries game_ids, up to 500; game_updated carries changes, up to 100).
    • Output Result: any dict; failures never break the host operation.
  7. Capability hooks: storefront, metadata, media, stats, emulator, and discovery. 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 tmpfs mounts for /home, /tmp, /run, /mnt, /media
  • Network isolation (disabled by default; --share-net only after a network grant)

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

  1. 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.
  2. Add plugin.json and plugin.py.
  3. Open OpenBox → Tools → Plugins.
  4. Enable your plugin in the list. Trust it if the host reports the sandbox is unavailable, and grant network if it declares that permission.
  5. If the manifest declares settings, check the form under Settings → Plugins; values are validated on save and passed to the hook as payload["settings"].
  6. Check the diagnostic log (openbox.log beside 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.
  7. Use Reinstall in the Plugins manager to repair an installed package without losing settings, stats, or trust.