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.jsonmanifest - Optional settings and actions
- A local connection back to HyperHQ
What Plugins Do
| Category | Examples |
|---|---|
| Game platform integrations | Import or launch games from external libraries |
| Emulator workflows | Setup helpers, game imports, save-state tools, updates |
| Achievement integrations | Sync achievements, progress, or leaderboard data |
| Hardware support | LEDs, cabinets, controllers, companion devices |
| Automation hooks | Send 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.
| Type | Entry point | Best for |
|---|---|---|
executable | executable field | Integrations needing their own runtime, external APIs, device access, or long-running jobs |
javascript | main field | Lightweight 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
- HyperHQ finds the plugin in the local
pluginsfolder or the HyperHQ plugin catalog. - HyperHQ reads
plugin.jsonfor the name, version, executable, platform targets, settings, actions, capabilities, and permissions. - HyperHQ launches the plugin when needed and passes connection details as environment variables.
- The plugin connects.
- Socket.IO plugins authenticate with a one-time challenge.
- Stdio plugins use the standard input and output of the process.
- 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.
{
"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
| Field | What the field controls |
|---|---|
executable | Default executable. Windows launches this file. A name without an extension gets .exe added on Windows. |
executableProviders | Per-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. |
communication | Transport choice. HyperHQ uses Socket.IO only when socketio.enabled is true and socketio is the preferred or fallback value. Otherwise HyperHQ uses stdio. |
capabilities | Features the plugin offers |
permissions | Access the plugin needs, shown to users |
pluginHosts | Apps allowed to run the plugin. Leave this out for HyperHQ only. Add "hyperspin" to run the plugin from HyperSpin and receive HyperSpin events. |
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:
- HyperHQ launches your plugin and creates a one-time challenge.
- The plugin reads
HYPERHQ_AUTH_CHALLENGE. - The plugin connects to
HYPERHQ_SOCKET_PORTon the default Socket.IO namespace. - The plugin sends
{ pluginId, challenge }with theauthenticateevent. - HyperHQ validates the challenge and replies with an
authenticatedevent holding a session token. - 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
| Variable | Value |
|---|---|
HYPERHQ_PLUGIN_ID | Plugin id from plugin.json |
HYPERHQ_PLUGIN_NAME | Plugin name from plugin.json |
HYPERHQ_PLUGIN_VERSION | Plugin version from plugin.json |
HYPERHQ_SOCKET_PORT | Local Socket.IO port. Also passed as --socket-port=<port>. |
HYPERHQ_AUTH_CHALLENGE | One-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.
Quick Links
| Guide | Use for |
|---|---|
| Get Started | Short path to 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 to build from |
New to plugins? Start with the onboarding guide. Wiring up an existing plugin? Go to the Socket.IO guide.