Introduction to HyperHQ Plugins

HyperHQ plugins extend the app without forcing every integration into the core installer. They are small companion programs with a plugin.json manifest, optional settings/actions, and a local communication channel back to HyperHQ.

What Are HyperHQ Plugins?

A HyperHQ plugin is a self-contained add-on. For executable plugins, HyperHQ launches a built executable beside the app and talks to it over Socket.IO.

Plugins commonly provide:

• Game platform integrations - Import or launch games from external libraries
• Emulator workflows - Setup helpers, game imports, save-state tools, and updates
• Achievement integrations - Sync achievement, progress, or leaderboard data
• Hardware support - LED, cabinet, controller, and companion-device workflows
• Automation hooks - Connect HyperHQ status to smart-home or companion systems

How Plugins Work

Most modern plugins use this flow:

1. HyperHQ discovers the plugin from the local plugins/ folder or the HyperHQ plugin catalog
2. HyperHQ reads plugin.json to learn the name, version, executable, platform targets, settings, actions, capabilities, and permissions
3. HyperHQ launches the plugin when needed and provides environment variables for local communication
4. The plugin authenticates with a one-time challenge over Socket.IO
5. HyperHQ and the plugin exchange requests, responses, data requests, status updates, and subscribed events

Plugin Types

HyperHQ supports a hybrid model:

Type	Best For
Executable plugins	Integrations that need their own runtime, external APIs, device access, or long-running jobs
JavaScript/app-side plugins	Lightweight app-side features and UI-focused extensions

Executable plugins are the common choice for platform, emulator, hardware, and automation integrations.

Manifest First

The manifest is the contract between HyperHQ, the plugin manager, and users.

plugin.json

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "Adds a focused workflow to HyperHQ.",
  "author": "Your Name",
  "type": "executable",
  "executable": "MyPlugin.exe",
  "executableProviders": {
    "windows": "MyPlugin.exe",
    "linux": "MyPlugin"
  },
  "communication": {
    "preferred": "socketio",
    "fallback": "stdio",
    "socketio": {
      "enabled": true
    }
  },
  "capabilities": [
    {
      "name": "game-import",
      "description": "Import games",
      "required": false
    }
  ],
  "permissions": [
    {
      "type": "network",
      "scope": "external-api",
      "description": "Call the configured service"
    }
  ]
}

Keep manifests short, accurate, and user-readable. They power plugin discovery, platform-aware launching, settings, permissions, and updates.

Plugin Architecture

Authentication Flow

HyperHQ uses challenge-response authentication for launched plugins:

1. HyperHQ launches your plugin and creates a one-time challenge.
2. The plugin reads HYPERHQ_AUTH_CHALLENGE.
3. The plugin connects to HYPERHQ_SOCKET_PORT on the default Socket.IO namespace.
4. The plugin sends { pluginId, challenge } with the authenticate event.
5. HyperHQ validates the challenge and returns a session token.
6. The plugin includes the session token with authenticated requests.

Quick Links

• Get Started - Short path for a first plugin
• Developer Guide - Full tutorial and examples
• Socket.IO Guide - Connection, authentication, and events
• API Reference - Method and payload lookup
• Templates - Starter code you can build from

Start with the onboarding guide if you want the short path, or jump straight to the Socket.IO guide if you are wiring up an existing plugin.