Plugin Repositories

HyperHQ accepts plugin packages from configured public GitHub repositories alongside the marketplace. Each repository supplies one plugin through published release assets.

Availability

Configured public repositories are development-only. Production builds disable the repository page, preload bridge, and install admission. The instructions below require a matching development build.

Adding a repository field to a locally installed manifest also supports a separate release-checking path. See manifest-only release checks for the distinction.

Add a repository in HyperHQ

1. Open Plugins and select the repository plus button, or open Plugin repositories from Settings.
2. Select Add repository.
3. Enter the public repository root, such as https://github.com/example/my-plugin.
4. Read the source status. A compatible release shows Ready to install.
5. Return to Plugins, open the plugin, and select Install.
6. Complete the plugin settings, account connection, or setup wizard.

Choose a publisher you trust. Executable plugins run under your signed-in OS account. Package hashes verify transfer integrity, not publisher trust.

HyperHQ saves sources across restarts. Use Refresh to check configured sources again. Release checks use a cache; repeated refreshes do not bypass GitHub request limits.

Supported URLs

Use an HTTPS GitHub repository root:

https://github.com/owner/repository

Equivalent casing, a trailing slash, an optional .git suffix, and www.github.com resolve to the same source.

The source parser rejects credentials, explicit ports, query strings, fragments, and deeper paths. Private repositories, other Git hosts, SSH URLs, branch URLs, release URLs, archive URLs, and direct asset URLs are unsupported.

HyperHQ reads GitHub release metadata. Source cloning and branch builds are outside this workflow.

Updates, release notes, and removal

Automatic updates default to off for each added source. Enable Automatic updates on the repositories page to update an already installed plugin. The switch does not install an absent plugin.

Manual updates use the normal plugin update action. HyperHQ compares semantic versions numerically, so 1.10.0 is newer than 1.9.0. Repository installation rejects a release older than the installed version.

Configured sources use GitHub's latest published stable release, including in beta or alpha HyperHQ builds. HyperHQ validates the package in this release. If the release lacks a compatible package, the source reports unsupported. HyperHQ does not search older releases for another package.

Release notes come from the GitHub release description. HyperHQ displays the description as text. A separate CHANGELOG.md asset is unnecessary for this workflow. The configured-source changelog currently exposes the selected release, rather than a complete release history.

Remove on the repositories page stops source checks and automatic updates. The installed plugin, settings, and plugin-owned data stay in place. Use the separate plugin uninstall action to remove an installation.

Publisher requirements

Publish one stable plugin ID and name per repository. Every supported release needs:

Item	Requirement
Release tag	Match the manifest version, with an optional leading v.
hyperhq-plugin.json	Attach exactly one descriptor with this case-sensitive filename.
Descriptor version	Set schemaVersion to 1.
Descriptor plugin	Include the complete runtime manifest.
Descriptor packages	List each supported OS/architecture ZIP with its exact asset filename and SHA-256.
ZIP assets	Attach the ZIPs to the same GitHub release.
ZIP contents	Put plugin.json and the runtime payload at the package root.
Release description	Write the release notes in the GitHub release body.

A manifest committed to the source tree does not replace the attached release descriptor. A release containing only an executable or GitHub-generated source archives does not satisfy the package contract.

Keep the descriptor's plugin object equal to each ZIP's plugin.json. HyperHQ checks the complete object, including permissions, settings, actions, and communication fields. Repository URL normalization is allowed; other manifest differences fail package validation.

Declare the configured repository URL in plugin.repository. Preserve the same ID and name across versions. A changed source identity needs removal and re-addition for review. An existing installation from another source or a conflicting ID/name blocks replacement.

Use a lowercase ID with letters, numbers, hyphens, or underscores. Start with a letter or number. IDs have a 128-character limit. Names must be valid directory names on Windows and Linux, without separators, leading dots, surrounding whitespace, or Windows reserved device names. Names have a 120-character limit. Core plugin names are reserved.

Package selection

Use windows, linux, or macos for platform. Executable packages must match the host architecture exactly, such as x64 or arm64.

Portable JavaScript packages support arch: "any". Native dependencies still need the correct OS and architecture. Supply exactly one compatible package per host. An exact-architecture package plus a matching JavaScript any package is ambiguous and rejected.

The asset field names an attached .zip asset, with matching case. Arbitrary URLs and GitHub source archives are unsupported. Use a 64-character hexadecimal SHA-256 digest of the finished ZIP.

Declare OS support in platforms and executable paths in executableProviders. Each advertised OS needs a real runtime payload. A Windows executable does not satisfy Linux support.

Missing host declarations mean HyperHQ. Use pluginHosts: ["hyperhq"] for an explicit declaration. A HyperSpin-only package is rejected by this HyperHQ repository workflow.

Example manifest

Replace the example repository URL with your public repository. Implement the lifecycle and action handlers described in Plugin Capabilities.

plugin.json

{
  "id": "example-plugin",
  "name": "Example Plugin",
  "version": "1.0.0",
  "description": "Example HyperHQ integration",
  "author": "Example Publisher",
  "type": "executable",
  "repository": "https://github.com/example/my-plugin",
  "pluginHosts": ["hyperhq"],
  "platforms": ["windows", "linux"],
  "executable": "example-plugin.exe",
  "executableProviders": {
    "windows": "example-plugin.exe",
    "linux": "example-plugin"
  },
  "capabilities": [
    {
      "name": "example",
      "description": "Provides the example integration",
      "required": true
    }
  ],
  "permissions": [],
  "settings": [
    {
      "key": "enabled",
      "type": "boolean",
      "label": "Enable integration",
      "defaultValue": true
    }
  ],
  "actions": [
    {
      "id": "check",
      "label": "Check connection",
      "description": "Check integration readiness",
      "icon": "fa-solid fa-check",
      "type": "secondary"
    }
  ]
}

The example capability describes the plugin. The Check connection button sends an execute request with data.action: "check". Your executable implements this action.

Build the release assets

Build and test the real Windows and Linux executables. Put the same manifest in both ZIPs:

example-plugin-windows-x64.zip
├── plugin.json
├── example-plugin.exe
└── assets/

example-plugin-linux-x64.zip
├── plugin.json
├── example-plugin
└── assets/

Generate the descriptor from the manifest and finished ZIPs. This PowerShell example computes real hashes:

Generate hyperhq-plugin.json

$releaseManifest = Get-Content -LiteralPath ./plugin.json -Raw |
    ConvertFrom-Json

$releasePackages = foreach ($targetPlatform in @('windows', 'linux')) {
    $assetName = "example-plugin-$targetPlatform-x64.zip"
    $assetHash = Get-FileHash -Algorithm SHA256 -LiteralPath $assetName
    @{
        platform = $targetPlatform
        arch = 'x64'
        asset = $assetName
        sha256 = $assetHash.Hash.ToLowerInvariant()
    }
}

@{
    schemaVersion = 1
    plugin = $releaseManifest
    packages = @($releasePackages)
} | ConvertTo-Json -Depth 50 |
    Set-Content -LiteralPath ./hyperhq-plugin.json -Encoding utf8

The output contains schemaVersion, the full plugin object, and package entries with platform, arch, asset, and sha256.

On Linux, calculate a ZIP hash with sha256sum example-plugin-linux-x64.zip, then write the same descriptor fields through your release tooling.

Attach hyperhq-plugin.json and both ZIPs to the stable release v1.0.0. Write the release description and publish the release. For the next version, update the manifest, rebuild both packages, compute fresh hashes, and attach a matching descriptor.

Validation and installation

HyperHQ checks source identity, tag/version agreement, manifest fields, host support, platform support, package selection, and asset metadata before offering a package.

Installation rechecks the source and validates archive size, SHA-256, ZIP integrity, complete manifest agreement, and the supplied runtime entry point. The installer restores Unix executable permissions before promotion. Replacement uses staging and rollback directories. Failed promotion or metadata persistence restores the prior installation.

Limit	Maximum
Descriptor	256 KiB
Downloaded ZIP	512 MiB
ZIP entries	4,096
Declared uncompressed content	1 GiB

Keep mutable data outside replaceable package-owned files. Use _hsm/Plugins/{PluginName}/ for plugin-owned cached data and downloaded assets. Test upgrades with saved settings and user data on every advertised OS/architecture.

On Windows, locked files and folder ACL failures need the existing stop/repair/retry flow. On Linux, verify dependencies, executable permissions, case-sensitive paths, and AppImage requirements where applicable. Publish macOS packages only after validating the macOS runtime.

Source status and errors

Result	Next step
Unsupported package	Check the descriptor, manifest, ZIP assets, and current host package.
No matching OS/architecture	Publish a package matching the current host.
Release not found	Check the repository URL and publish a public stable release.
Rate limited	Wait before checking again.
Unavailable	Restore connectivity or wait for GitHub availability, then refresh.
Identity conflict	Check installed and configured plugin IDs, names, and publisher source.

An unavailable source does not remove installed files.

Related guides and source contracts

• Using Plugins
• Plugin Developer Guide
• Plugin Capabilities
• Windows and Linux Plugin Requirements
• Repository descriptor validation
• Repository configuration and release selection
• Build availability

Source contracts checked on September 27, 2026. Native Windows and Linux package acceptance and an explicit production launch are required before configured repositories become production functionality.