Extension Marketplace

The Extension Marketplace is a browsable catalog of integration templates and services you can install to add functionality to a ControlBird node. Each extension packages everything needed to provision a feature (a manifest descriptor, optional SQL seed files, and provision/deprovision scripts) into a single archive. The marketplace handles the full lifecycle: discovery, install and uninstall with explicit state tracking, dependency resolution, upgrades, and live status updates shown in the UI.

Extensions come from two kinds of sources. The official catalog is curated by ControlBird. Community extensions are installed directly from an HTTPS git URL, letting you pull in templates that live outside the official catalog. Both follow the same install pipeline once the archive is available.

Browsing the Catalog

When you open the Extension Marketplace, the UI shows a cached copy of the catalog for a fast initial render. If that cache is present and fresh it displays immediately; otherwise the UI fetches the live catalog. Each entry is built from the extension's manifest.json descriptor.

Extensions are organized into categories so you can narrow the list with search and filter chips. The category is derived from each extension's type and tags:

A dedicated section highlights a hand-picked set of featured extensions: mqtt-service, http-service, esphome, tasmota, system-dashboards, and homeassistant. Opening an extension shows a detail window with its description, icon, and declared dependencies.

The Extension Manifest

Every extension is described by a manifest.json at the root of its archive. It is the source of truth for both the catalog listing and the install pipeline.

Required fields

Optional fields

{
  "id": "mqtt-service",
  "name": "MQTT Service",
  "version": "1.2.0",
  "description": "Connect to an MQTT broker and map topics to entities.",
  "icon": "radio",
  "type": "service",
  "protocolType": "MQTT",
  "tags": ["protocol", "messaging"],
  "dependencies": [],
  "provisionProgram": "/Root/Programs/mqtt-provision",
  "editions": ["ce", "cloud"]
}

Archive layout

Extension archives are tar.gz files. An archive contains a manifest.json, an optional sql/ directory of seed files, an optional icon.png or icon.svg, and an optional README.md. You can request a specific version, which is validated against the manifest version before the archive is served.

How Installation Tracks State

Each installed extension is tracked with its own install state, so the marketplace always knows what is installed, which version, and whether an upgrade is available. An installed extension moves through a clear set of states (Installing, Provisioning, Installed, Uninstalling, Upgrading, or Failed), and a failed install records an error message you can read in the UI.

The Install Pipeline

A catalog install moves through a clear sequence: the extension archive is fetched and unpacked, any bundled seed configuration is applied, and the provision step runs (the status shows Provisioning). On success the extension becomes Installed; if any step fails it becomes Failed with an error message you can read in the UI.

Declaring created entities

Clean uninstalls depend on knowing exactly which entities an extension created. A provision script should report a created array of entity paths. If the script does not declare one, the marketplace infers what changed instead, which is less precise.

Dependencies and Cascade Uninstall

When an extension declares dependencies, the marketplace resolves and installs those required extensions automatically. Removal works in the opposite direction: before uninstalling, a confirmation dialog lists every extension that depends on the one you are removing. If you confirm, the parent and all of its dependents are removed together atomically.

The uninstall sequence is:

1. The confirmation dialog enumerates dependents.
2. The entities created by the extension are removed.
3. The deprovision program runs for any extension-specific cleanup.
4. The extension's bundled files are removed.

Upgrading Extensions

When a newer version is published, the marketplace flags an available update and shows the latest catalog version. Upgrading is an uninstall of the current version followed by an install of the new one, with the status showing Upgrading while it runs. On completion the extension returns to Installed, or becomes Failed with an error message if any step fails.

Community Extensions

To install an extension that is not in the official catalog, provide an HTTPS git URL and an optional branch, tag, or commit. The repository is cloned, its manifest.json is validated, and the same install pipeline runs as for a catalog extension. The originating git URL is recorded so you can see where a community extension came from.

Reliability and Reconciliation

Extension operations run with a generous time budget. If an operation is left in a transient state (Installing, Provisioning, Uninstalling, or Upgrading) beyond that window, the UI surfaces an error so the situation is visible rather than silently stuck.

The marketplace also repairs states left over from interrupted operations, so an extension does not stay stuck in a transient state after an unexpected interruption.

Limitations

• The catalog tracks a single version per extension; multi-version catalog support is a follow-up.
• Provision scripts should explicitly declare created entities via a created array; otherwise uninstall relies on the less precise before/after comparison.
• Community extensions are unverified and can create schemas, entities, and run arbitrary scripts.
• Bundled README.md files are rendered with strict sanitization because their sources are untrusted.

Many extensions provision protocol services. For protocol-specific setup once an extension is installed, see the MQTT, Modbus, and OPC UA guides, or continue your initial setup in the Configure your system walkthrough.