Skip to main content

Introduction to HyperHQ Plugins

Plugins add features to HyperHQ without putting every integration into the core installer.

A plugin is a self-contained add-on with three parts:

  • A plugin.json manifest
  • Optional settings and actions
  • A local connection back to HyperHQ

What Plugins Do​

CategoryExamples
Game platform integrationsImport or launch games from external libraries
Emulator workflowsSetup helpers, game imports, save-state tools, updates
Achievement integrationsSync achievements, progress, or leaderboard data
Hardware supportLEDs, cabinets, controllers, companion devices
Automation hooksSend HyperHQ status to smart-home or companion systems

Plugin Types​

HyperHQ supports two plugin types. Set the type with the type field in plugin.json.

TypeEntry pointBest for
executableexecutable fieldIntegrations needing their own runtime, external APIs, device access, or long-running jobs
javascriptmain fieldLightweight app-side features and UI-focused extensions

Most platform, emulator, hardware, and automation plugins are executable plugins. HyperHQ launches the built executable from the plugin folder and talks to the plugin over Socket.IO or stdio.

How Plugins Work​

  1. HyperHQ finds the plugin in the local plugins folder or the HyperHQ plugin catalog.
  2. HyperHQ reads plugin.json for the name, version, executable, platform targets, settings, actions, capabilities, and permissions.
  3. HyperHQ launches the plugin when needed and passes connection details as environment variables.
  4. The plugin connects.
    • Socket.IO plugins authenticate with a one-time challenge.
    • Stdio plugins use the standard input and output of the process.
  5. HyperHQ and the plugin exchange requests, responses, data requests, status updates, and subscribed events.

The Manifest​

plugin.json is the contract between your plugin, the HyperHQ plugin manager, and users. HyperHQ uses the manifest for:

  • Plugin discovery
  • Platform-aware launching
  • Settings and permissions
  • Updates

Keep manifests short, accurate, and readable.

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"
}
]
}

Key Fields​

FieldWhat the field controls
executableDefault executable. Windows launches this file. A name without an extension gets .exe added on Windows.
executableProvidersPer-platform executables (windows, linux, macos). Linux and macOS check here first, then executableLinux or executableMac, then executable. The plugin catalog also uses this field to pick the package for each platform.
communicationTransport choice. HyperHQ uses Socket.IO only when socketio.enabled is true and socketio is the preferred or fallback value. Otherwise HyperHQ uses stdio.
capabilitiesFeatures the plugin offers
permissionsAccess the plugin needs, shown to users
pluginHostsApps allowed to run the plugin. Leave this out for HyperHQ only. Add "hyperspin" to run the plugin from HyperSpin and receive HyperSpin events.
Linux Builds

On Linux and macOS, HyperHQ adds the execute bit to your executable if the bit is missing. If executable points to a .exe with a matching .dll beside the file, HyperHQ runs the .dll with dotnet.

Authentication Flow​

Socket.IO plugins use challenge-response authentication:

  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 replies with an authenticated event holding a session token.
  6. The plugin includes the session token with authenticated requests.

The challenge expires after 30 seconds and works once. To reconnect after a dropped connection, send { pluginId, sessionToken } with authenticate instead.

Launch Environment Variables​

VariableValue
HYPERHQ_PLUGIN_IDPlugin id from plugin.json
HYPERHQ_PLUGIN_NAMEPlugin name from plugin.json
HYPERHQ_PLUGIN_VERSIONPlugin version from plugin.json
HYPERHQ_SOCKET_PORTLocal Socket.IO port. Also passed as --socket-port=<port>.
HYPERHQ_AUTH_CHALLENGEOne-time challenge for the first connection

Stdio plugins get PLUGIN_ID and PLUGIN_SETTINGS and none of the HYPERHQ_ variables. Socket.IO plugins also get PLUGIN_SETTINGS, but the Socket.IO Guide explains why you should read settings from initialize instead. The guide also has the full variable list.

GuideUse for
Get StartedShort path to a first plugin
Developer GuideFull tutorial and examples
Socket.IO GuideConnection, authentication, and events
API ReferenceMethod and payload lookup
TemplatesStarter code to build from

New to plugins? Start with the onboarding guide. Wiring up an existing plugin? Go to the Socket.IO guide.