AiHummer docs
v1.0.x ▾
v1.0.x stable
RU EN
Marketplace & plugins /Install & updates

Install & updates

v1.0.x · updated 2026-06-26

Installing a plugin in AiHummer is a single click in the admin UI, but behind that click is a deterministic, host-native lifecycle. The platform downloads the plugin, runs its declared install steps, renders a sandboxed systemd unit, and only considers the plugin healthy once it answers a health check. Each installation then keeps itself up to date on its own.

One-click install from the admin UI

You install and manage plugins from the admin UI, which is backed by the admin module API:

GET  /v1/admin/modules
POST /v1/admin/modules/{slug}/install

There is nothing to wire by hand: pick a plugin from the catalog, click install, and the deployer takes over.

The SystemdDeployer flow

Under the hood the SystemdDeployer performs these steps:

  1. Download a tarball for the selected plugin.
  2. Run the manifest install[] steps declared by the plugin.
  3. Render a sandboxed systemd unit for the plugin.
  4. Poll /healthz until the service reports healthy.
download tarball ─▶ run install[] steps ─▶ render sandboxed systemd unit ─▶ poll /healthz ─▶ active

Only when /healthz succeeds is the installation marked active — a plugin that fails to come up does not silently count as installed.

Host-native, sandboxed systemd — not Docker

Every plugin runs as its own sandboxed systemd service. There are no containers, no Docker, no orchestrator: a plugin is a managed Linux service with its own unit, port and sandbox restrictions, supervised by systemd like the rest of the install.

[!WARNING] AiHummer is host-native. Plugins are deployed as sandboxed systemd services from a release tarball — never as Docker containers. If a guide tells you to “run the plugin container”, it does not describe AiHummer.

Health gating with /healthz

The deployer polls the plugin’s /healthz endpoint before declaring success. This health gate is what makes one-click install safe: a broken or mis-configured plugin is caught during install rather than discovered later in production.

Per-installation auto-update

Updates are handled per installation. Each installed plugin can auto-update itself on its own schedule, so keeping plugins current does not require a manual re-install each time a new version reaches the catalog. The same download → install steps → render unit → health-check flow runs for an update as for a first install.

[!TIP] Because auto-update is per installation, you can keep some plugins pinned while letting others track the latest — each installation manages its own lifecycle.

Multi-source catalog

The catalog is no longer tied to a single URL. In Plugins → Sources (Admin UI, or POST /v1/admin/modules/catalog/sources) you can add an extra source — for example the community catalog of third-party plugins. The gateway syncs every enabled source on startup and on the auto-update interval.

  • The official source (first-party modules) is pinned and trusted by default — a separate object that is not overwritten by other sources.
  • Private/community sources are added by the operator; every catalog entry has an origin, and that origin decides which anchor the signature is verified against (official → pinned key, private → trust store).

For publishing to the community catalog, see Publishing a plugin.

Trust model and the pinned key

Installation verifies a plugin’s signature by its source:

  • official → verified against the registry key pinned in core. Trusted by default, no operator action.
  • private (side-load) → verified against the instance trust store; the author key is approved by the operator on upload (one click).
  • unsigned → rejected, except in dev mode (AIHUMMER_PLUGIN_DEV_UNSIGNED=1, local development only).

Signed updates

An update re-runs the same signature gate as the first install: when moving to a new version the signature is verified again against the same trust anchor. An update cannot bypass the check — you can’t elevate trust through an update.

The Official badge and ranking

In the Web UI catalog, plugins from AiHummer carry an Official badge and rank first. Third-party plugins show without a badge and sort by download count. The Official flag is derived from an entry’s origin (official) — it can’t be set by hand in the manifest.

Where to next