API local administrator

Check for a new release. Queries the GitHub releases API for vindeckyy/OpenBoxGL (30-second timeout) and returns:

{
  "current": "0.9.0",
  "latest": "0.9.0",
  "available": true,
  "notes": "...",
  "appimage": "https://github.com/vindeckyy/OpenBoxGL/releases/download/.../OpenBox-x86_64.AppImage",
  "checksum": "sha256:...",
  "checksum_url": "...",
  "page": "https://github.com/.../releases/tag/..."
}

Rules:

• Pre-release and build-suffixed tags are never available.
• The AppImage asset must come from the trusted https://github.com/vindeckyy/OpenBoxGL/releases/download/ prefix and a SHA-256 checksum must be present (asset digest or .sha256 file); otherwise 400 with a clear reason.
• GitHub failures return 400 ("GitHub releases request failed (...)" / "Could not reach GitHub releases: ..."). Setting GITHUB_TOKEN (or GH_TOKEN) in ~/.env authenticates the request for a higher rate limit.

Download and atomically install the verified update into the running AppImage. Prerequisites:

• APPIMAGE must be set (the process must run from an AppImage), else 400 "Automatic updates require the OpenBox AppImage."
• The update must be available and its URLs trusted.
• The download streams with a 2 GiB cap and the SHA-256 is verified before the swap.
• The current AppImage is renamed to <name>.previous<ext>; a failed swap restores it.

Returns {"installed": "<version>", "backup": "<path>"}. Restart to use the update.

{"force": bool} stops every running game (SIGTERM, or SIGKILL with force: true) and returns {"stopped": <count>, "forced": bool}. Games that already exited are skipped.

Restore the library from library.json.bak (see Data and recovery). Success returns {"ok": true, "games": <count>}; an unusable backup raises 503-class errors (surfaced as 400 with the message).

Write the desktop entry and icon for the running AppImage: ~/.local/share/applications/io.openbox.GameLauncher.desktop and ~/.local/share/icons/hicolor/scalable/apps/io.openbox.GameLauncher.svg. Requires APPIMAGE (else 400). Returns {"desktop": "<path>"}.

?platform=<name> returns {"themes": [...], "selected": "...", "global": "...", "mappings": {...}}. Stock themes are installed on demand (Midnight Circuit, Phosphor Terminal, Harbor Light, Cinema Marquee, Nordic Mist). selected is the per-platform mapping when platform is given, else the global theme.

{"name": "theme-name"|"", "platform": ""} sets the global theme (or clears it with ""); with platform, sets/clears a per-platform mapping. Unknown theme file: 400. Returns {"selected", "platform"}.

{"path": "/path/to/theme.css"} copies a CSS file into themes/ (.css suffix required). Returns {"theme": "<stem>"}.

Open the themes folder in the file manager via xdg-open (missing xdg-open: 400). Returns {"path"}.

{"plugins": [{"id", "name", "version", "entry", "hooks", "enabled"}, ...]} sorted by id. Invalid packages are skipped.

{"path": "/path/to/plugin-dir-or.zip"} installs or updates a plugin package (safe extraction, staging, rollback on failure). Returns {"plugin": {...manifest..., "updated": bool}}.

{"id", "enabled": bool} enables/disables a plugin (persisted in plugins-state.json). Returns {"enabled": bool}.

{"id"} moves the plugin directory to plugins/.removed/<id>-<timestamp> (reversible by moving it back) and clears its disabled state. Returns {"removed": "<id>"}.

{"catalog": [...]} from the bundled local catalog, falling back to the remote catalog (raw.githubusercontent.com/vindeckyy/OpenBoxGL/master/plugins/catalog.json, 20-second timeout, 4 MiB cap).

{"id"} downloads the catalog entry's package (128 MiB cap, SHA-256 verified when the entry provides one, 120-second timeout) and installs it. Unknown id or local_only entries raise 400 ("This catalog entry is documentation-only. Install local plugin packages manually."). Returns {"plugin": {...}}.

See Plugins for the manifest and hook contract.

?locale=en|es|de|fr|pt returns {"locale", "strings": {...}}; unknown locales fall back to English.

{"packs": [{"id", "name", "description", "kinds", "active"}, ...]}. Bundled packs: clear-logos-default, controller-xbox, controller-playstation, badges-core.

{"categories": {...}} platform-to-category mapping (Nintendo, Sony, Microsoft, Computer, Arcade, Adventure, ...) with user overrides merged.

{"id": "<pack id>"} activates a pack (and sets the controller prompt pack/hint for controller packs). Unknown pack: 400. Returns {"pack": {...}, "settings": {...}}.

{"log": "<last 250 KB of openbox.log>"}. The log redacts tokens, passwords, API keys, and authorization headers, but can contain game names and local file paths.

?name=<theme> serves the theme CSS with revalidation headers; unknown themes return an empty stylesheet.

{"platform", "documents": [{"name", "path"}, ...]} replaces the platform's document list (capped at 100 entries). Returns {"saved", "count"}.