Skip to main content

Installing Plugins from GitHub

Plugins add features to HyperHQ and your HyperSpin setup. Add a publisher's GitHub repository to see its plugin in Plugins, then choose when to install and update.

HyperHQ selects the release package for your operating system and CPU architecture. Your repository list stays saved across restarts.

Before you start​

  • Configure your HyperSpin installation folder in Settings, Paths.
  • Check the publisher's requirements for your operating system and install any required software.
  • Leave enough free disk space for the download and extraction.
  • Connect to the internet for the repository check and download.
  • Review the publisher, plugin description, and release notes. Choose plugins from publishers you trust.

The same steps apply on Windows and Linux. The publisher must provide a package for your operating system and CPU architecture.

Get the repository URL​

Copy the public repository URL supplied by the publisher. Use the repository's main page:

https://github.com/owner/repository

A trailing slash or .git suffix is accepted.

Use the repository URL rather than a link to a release, branch, ZIP, or individual file. Private repositories, SSH links, and other Git hosts are unsupported. Leave credentials and URL parameters out of the address.

The publisher must attach a HyperHQ release descriptor and a compatible ZIP to a stable GitHub release. A repository containing source code alone does not provide an installable plugin. Developers should follow Publishing Plugins on GitHub.

Add a repository​

  1. Open Plugins from the HyperHQ sidebar.
  2. Select Plugin repositories. The Add a repository dialog opens.
  3. Paste the URL into Repository URL.
  4. Select Add repository.
  5. Check the plugin name and source status. A compatible uninstalled plugin shows Ready to install.
  6. Select Release notes when available and review the changes.

To add another source from the repositories page, select Add repository.

Adding a repository does not install its plugin. Choose the installation from the Plugins page.

Install the plugin​

  1. Select Plugins at the top of the repositories page to return to your plugin list.
  2. Find the plugin under All plugins or Discover. Show New Plugins also shows plugins ready to install.
  3. Select Install on the plugin card.
  4. Check the name in the Install Plugin? dialog, then select Install Plugin.
  5. Leave HyperHQ open until installation finishes.
  6. Open Details for the installed plugin and complete its settings, account connection, or setup wizard.

Use the plugin's settings or actions from Details. The available controls depend on the plugin. Some plugins add a page or action. Others run in the background with HyperSpin.

HyperHQ checks the downloaded package before installing. Read any failure message before retrying.

Check for updates​

Open Plugin repositories and select Refresh. Installed entries show your version and an update status:

StatusMeaning
Update availableA newer compatible release is available.
Up to dateNo newer version was found in the selected stable release.
Update status unavailableHyperHQ did not complete the release check. Read the error and retry later.

HyperHQ uses the repository's latest published stable release. Drafts and releases marked as prereleases are excluded. HyperHQ does not offer a version picker or fall back to an older release when the latest release lacks a compatible package.

Release checks are cached. Wait before refreshing again when a newly published version has not appeared.

To update manually:

  1. Open Plugins and select Check for Updates, or check the plugin from Details.
  2. Select View Changelog and read the release description.
  3. Select Update Now when an update is available.
  4. Open Activity to follow progress.
  5. Check the plugin after the update finishes.

Version numbers are compared in order. For example, 1.10.0 is newer than 1.9.0. HyperHQ rejects a release older than your installed version.

Choose automatic updates​

Automatic updates start off for each repository.

  1. Open Plugin repositories.
  2. Find the source you want to update automatically.
  3. Select Automatic updates off to turn the option on.

Select Automatic updates on to turn the option off again. The choice applies to that repository's installed plugin. Turning automatic updates on does not install a plugin you have not installed yet.

Enable this option for publishers whose future releases you trust.

Remove a repository​

Select Remove beside the source on Plugin repositories. HyperHQ stops configured-source checks and automatic updates. Your installed plugin and settings stay in place.

Use the separate plugin removal action in Plugins to remove the installation.

Common problems​

The source shows not found​

Check the URL and confirm the repository is public. The publisher also needs a published stable release. Private repositories and repositories without an accessible release produce this result.

The source shows unsupported​

Read the detailed error. The release needs a valid hyperhq-plugin.json descriptor and a ZIP for your operating system and CPU architecture. Ask the publisher to check the release assets.

If the message reports an identity conflict, check your installed plugins and saved sources. HyperHQ blocks conflicting plugin IDs, names, and publisher sources. Review a publisher identity change before removing and re-adding the source.

The source shows unavailable or rate limited​

Check your internet connection, then retry later. HyperHQ needs GitHub and the official HyperHQ plugin catalog for source validation. Repeated refreshes do not bypass GitHub request limits.

An unavailable status does not mean your plugin is up to date. Failed source checks leave verified installed files in place.

Installation fails​

  1. Open Activity and read the failure reason.
  2. Confirm your HyperSpin folder is configured in Settings, Paths.
  3. Check free disk space and close programs using the plugin folder.
  4. Retry the installation.

On Windows, follow the folder-repair prompt when shown. On Linux, check folder ownership, executable permissions, required software, and filename case.

For a repeated hash, archive, manifest, or missing runtime error, ask the publisher for a corrected release. When an update fails, HyperHQ restores the previous version.

The plugin is installed but does nothing​

Open Details and complete the plugin's setup action. Check any required program or account connection, then save your settings.