Quick Start Guide

Build a small executable plugin, install it locally, and confirm HyperHQ can talk to it.

Prerequisites

• HyperHQ installed and running
• A language/runtime supporting your target operating system
• For Linux, follow the plugin release requirements. Windows executable examples below need a Linux build and matching manifest entry.
• A Socket.IO client library for your language
• Basic JSON knowledge

Official starter docs are available for:

Template	Best For
Go Starter	Small self-contained binaries
C# Starter	.NET integrations on Windows or Linux
Python Starter	Fast prototypes and scripts

Step 1: Create the Plugin Folder

HyperHQ loads one plugin per folder. For a local install, that folder goes under your HyperSpin install directory:

Folder layout

HyperSpin/
└── plugins/
    └── my-plugin/
        ├── plugin.json
        ├── MyPlugin.exe    # Windows package
        ├── MyPlugin        # Linux package
        ├── icon.png        # optional
        └── README.md       # optional

Use the HyperSpin root shown in Settings, Paths. Default plugin roots are C:/ProgramData/HyperSpin/plugins/ on Windows and ~/HyperSpin/plugins/ on Linux. Use your configured root for a custom installation.

The folder name should be stable. The plugin ID inside plugin.json must be unique. If you ship multiple platform builds, list them with executableProviders so HyperHQ can launch the right file.

Step 2: Add a Manifest

plugin.json

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "author": "Your Name",
  "type": "executable",
  "description": "Adds a focused workflow to HyperHQ.",
  "executable": "MyPlugin.exe",
  "executableProviders": {
    "windows": "MyPlugin.exe",
    "linux": "MyPlugin"
  },
  "communication": {
    "preferred": "socketio",
    "fallback": "stdio",
    "socketio": {
      "enabled": true
    }
  },
  "capabilities": [
    {
      "name": "game-import",
      "description": "Import games from an external source",
      "required": false
    }
  ],
  "permissions": [
    {
      "type": "network",
      "scope": "external-api",
      "description": "Connect to the configured service"
    }
  ],
  "settings": [
    {
      "key": "enabled",
      "label": "Enabled",
      "type": "boolean",
      "defaultValue": true
    }
  ],
  "actions": [
    {
      "id": "sync_games",
      "label": "Sync Games",
      "description": "Run the import workflow"
    }
  ]
}

Keep the manifest honest. If a plugin needs network access, filesystem access, credentials, or process launching, say so clearly.

Step 3: Build the Executable

Use the command that matches your template or language:

Go on Linux

go build -o MyPlugin

Go on Windows

go build -o MyPlugin.exe

C# on Linux x64

dotnet publish -c Release -r linux-x64 --self-contained true -p:PublishSingleFile=true

C# on Windows x64

dotnet publish -c Release -r win-x64 --self-contained -p:PublishSingleFile=true

Python

pip install pyinstaller
pyinstaller --onefile --name MyPlugin plugin.py

Build Python executables on the target operating system. Set executableProviders to the actual output filename. For C#, this depends on the project assembly name. Preserve required files from the publish directory.

Step 4: Connect and Authenticate

When HyperHQ launches an executable plugin, it provides the connection details through environment variables.

Variable	Purpose
HYPERHQ_PLUGIN_ID	Plugin ID from the manifest
HYPERHQ_AUTH_CHALLENGE	One-time challenge used to authenticate
HYPERHQ_SOCKET_PORT	Local Socket.IO port
HYPERHQ_PLUGIN_NAME	Display name from the manifest
HYPERHQ_PLUGIN_VERSION	Version from the manifest
PLUGIN_SETTINGS	Serialized plugin settings for the current launch

For stdio-mode plugins, HyperHQ sends JSON requests over stdin/stdout instead. Socket.IO is the better default for real-time progress and longer workflows.

Generic Socket.IO flow

import { io } from 'socket.io-client';

const pluginId = process.env.HYPERHQ_PLUGIN_ID || 'my-plugin';
const challenge = process.env.HYPERHQ_AUTH_CHALLENGE;
const port = process.env.HYPERHQ_SOCKET_PORT || '52789';
const socket = io(`http://localhost:${port}`, { reconnection: true });

socket.on('connect', () => {
  socket.emit('authenticate', { pluginId, challenge });
});

socket.on('authenticated', (response) => {
  if (!response.success) {
    console.error('Authentication failed:', response.error);
    return;
  }

  sessionToken = response.sessionToken;
});

socket.on('request', async (message) => {
  const result = await handleRequest(message);

  socket.emit('response', {
    id: message.id,
    type: 'response',
    data: result
  });
});

Notice the URL uses the default Socket.IO namespace. Do not append /plugin.

Step 5: Test in HyperHQ

1. Restart HyperHQ.
2. Open Settings -> Plugins.
3. Find your plugin.
4. Run the test action.
5. Check plugin logs if authentication or launch fails.

Common Issues

Plugin doesn't appear

• Check plugin.json is valid JSON.
• Make sure the folder is under the correct plugins/ directory.
• Confirm id, name, version, type, and executable are present.

Authentication fails

• Read HYPERHQ_AUTH_CHALLENGE from the environment.
• Connect to the port in HYPERHQ_SOCKET_PORT.
• Use the default namespace: http://localhost:${port}.
• Emit authenticate immediately after the Socket.IO connection opens.

Plugin starts but does nothing

• Confirm it listens for request.
• Respond with response, not plugin:response.
• Include the original request id in every response.
• Send statusUpdate during long operations.

Next Steps

• Read the Socket.IO Guide for the full event contract.
• Use the API Reference when you need request payloads.
• Start from a template if you want complete working code.