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.

Source integration does not enable this feature in an installed production build. Release owners follow the repository acceptance checklist before the intentional production launch.

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.

If GitHub is offline or rate limited, HyperHQ keeps verified installed files and their version visible. An unavailable source is not reported as up to date.

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.

HyperHQ reserves IDs in its official API plugin list. Community publishers can choose any other valid ID without submitting their plugin to that list. A user opts in by adding the public repository URL. A source cannot replace an installed plugin whose persisted identity belongs to a different ID, even when its plugin.json names the same repository.

Installation rechecks the official catalog. If that check fails, the install stops and keeps existing files. A source without a cached official catalog check appears unavailable until refresh succeeds.

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 using the checked release command. The output contains schemaVersion, the complete plugin object, and package entries with platform, arch, asset, and the ZIP's SHA-256.

Generate a checked release descriptor

From a current HyperHQ source checkout providing the publishing tool, run:

npm run plugin:repository:prepare -- ./plugin.json ./hyperhq-plugin.json windows/x64=./example-plugin-windows-x64.zip linux/x64=./example-plugin-linux-x64.zip

The tool validates archive limits, safe extraction, manifest agreement, and runtime payloads before writing SHA-256 package entries. Failed checks leave an existing descriptor untouched. The command prepares local release metadata; publishing still happens through GitHub.

Use quoted absolute paths for packages outside the checkout. Build and test every advertised OS and architecture before adding targets.

Generate the descriptor after finishing every ZIP. Attach the generated hyperhq-plugin.json and those exact ZIPs to a stable GitHub release tagged v1.0.0. Use the release description for notes. To publish v1.1.0, update the version in the manifest and both ZIPs, rebuild the packages, regenerate the descriptor, then test a fresh install and an upgrade with saved settings. Do not replace assets for a version already installed by users.

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 or the official HyperHQ catalog, 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 acceptance and production launch
• Repository descriptor validation
• Repository configuration and release selection
• Checked release preparation command
• Build availability

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