// OPENBOX DOCS

System Architecture & Reliability

Deep dive into OpenBox's offline-first engine, loopback server, WebKitGTK native host bridge, and state recovery model.

OpenBox is engineered with a strict local-first, dependency-free runtime architecture. It operates entirely on your machine without requiring remote accounts, cloud sync dependencies, or background telemetry services.

Core Architectural Layers

1. Zero-Dependency Loopback Core

The runtime engine uses Python 3's built-in standard library (http.server, urllib, sqlite3, json, concurrent.futures, hashlib, gzip).

  • Runs bound to 127.0.0.1 on an ephemeral port chosen at startup, with strict Host and Origin validation; the host address is not configurable by design.
  • No third-party Python packages are bundled or required at runtime.
  • Fast cold start: native-host launch to server-ready measured at ~242ms on the reference machine (see docs/development/PERF.md).

Interactive REST API Explorer

Test local OpenBox endpoints, view response structures, and generate cURL requests

Local loopback only (127.0.0.1:${PORT})

OpenBox chooses a random loopback port. The copied command reads server.port (and server.token for protected routes) from OPENBOX_DATA_DIR.

GEThttp://127.0.0.1:${PORT}/api/v1/library

Fetch all games, metadata, launch profiles, and session statistics.

Simulated 200 OK JSON Responseapplication/json · UTF-8
{
  "games": [
    {
      "id": 0,
      "game_id": "game-a1b2c3d4e5f6",
      "name": "The Legend of Zelda: Ocarina of Time",
      "platform": "Nintendo 64",
      "year": 1998,
      "developer": "Nintendo",
      "genre": "Action-Adventure",
      "playtime_seconds": 14200,
      "play_count": 18,
      "progress": "Completed",
      "favorite": true
    },
    {
      "id": 1,
      "game_id": "game-9f8e7d6c5b4a",
      "name": "Cyberpunk 2077",
      "platform": "PC",
      "year": 2020,
      "developer": "CD Projekt Red",
      "genre": "RPG",
      "playtime_seconds": 35600,
      "play_count": 42,
      "wine_prefix": "/home/deck/.local/share/bottles/prefixes/gaming"
    }
  ],
  "playlists": [],
  "filter_presets": [],
  "ra_configured": false,
  "discovery": {},
  "media_epoch": 3
}

2. WebKitGTK Native Host & IPC Bridge

When launched via native binary or AppImage, OpenBox spawns a native C/WebKitGTK host process:

  • Hardware-accelerated WebGL and 2D canvas rendering
  • Native window management, borderless fullscreen, and Wayland/X11 display protocol compatibility
  • Controller input uses the browser's Web Gamepad API inside the WebKitGTK view (the injected onGamepad bridge is a deliberate no-op stub; see docs/native-host-contract.md)

3. Atomic State Store & Recovery

OpenBox treats library state as critical user data:

  • Atomic File Writes: Mutations are written to temporary staging files (.<path>.tmp), flushed with fsync, and swapped into place using POSIX rename(2) / os.replace to prevent corruption on sudden power loss.
  • Automated Snapshot Rotation: Rotating snapshots (library.json.snapshots/<stamp>-<token>.json) are retained automatically on committed mutations using zero-copy hardlinks and debouncing.
  • Deduplication Engine: Canonical identity hashing prevents duplicate entries when games exist simultaneously across Steam, Heroic, and ROM folders.

4. Asynchronous Background Job System

Heavy operations (metadata database synchronization, bulk save backups, full emulator catalog scans) run in non-blocking worker threads managed by JobManager. Progress, speed, and error telemetry are polled via GET /api/jobs.