Install an Extension

Hands-on: browse the marketplace and install an integration extension in one click.

In this tutorial you will open the Extensions app, find an integration in the catalog, and install it in a single click. By the end you will have a working extension whose install state you can watch update live, and you will know how to upgrade and uninstall it again. We will use the esphome extension as the worked example because it pulls in a dependency, which lets you see automatic dependency resolution in action.

Looking for full details?

This is a hands-on tutorial. For the complete reference (every field, option, and edge case), see the Extension Marketplace reference, or browse the live extension catalog to see what's available.

What you'll need

  • Access to a running ControlBird node and its control plane.
  • Permission to open the Extensions app (the marketplace app, ID extension-marketplace).
  • Network connectivity from the node to the catalog API, so the UI can browse the catalog and download extension archives.
  • About five minutes. A single extension operation finishes well within a few minutes, even on a slow install.

No setup before you start

You do not need to pre-create anything. Installing an extension records it and runs the extension's setup for you. Everything in this tutorial happens inside the Extensions app.

Step by step

  1. Open the Extensions app from the control plane. On first open, the UI shows the catalog. A cached copy renders instantly; otherwise it fetches the live catalog.

    Expected result: a grid of extension tiles, with a featured section at the top highlighting hand-picked extensions such as mqtt-service, http-service, esphome, tasmota, system-dashboards, and homeassistant.

  2. Find the extension. Either click the esphome tile in the featured section, or type a name, tag, or part of the description into the search box at the top. You can also narrow the grid with the category filter chips: All, Installed, Protocols, Cloud, Notifications, Dashboards, and Integrations.

    Expected result: the grid filters down to matching extensions as you type or select a chip.

  3. Open the detail window. Click the esphome tile. The detail window shows the manifest data: icon, name, version, type, description, supported editions, declared dependencies, tags, and the bundled documentation (rendered from the extension's README.md if present).

    Expected result: because esphome declares a dependency on mqtt-service, you will see a Requires section listing it. Clicking a dependency opens its own detail window.

  4. Install it. Click the Install ESPHome button. This queues the install operation. The button label updates to reflect progress (for example, Queued, then Installing) as the backend works through the steps.

    Expected result: the extension shows a status of Installing, then moves to Provisioning as its setup is applied.

  5. Watch the dependency resolve. Because esphome requires mqtt-service, the marketplace installs the dependency automatically and recursively if it is not already present. You do not need to install it by hand first.

    Expected result: both mqtt-service and esphome end up in the Installed list.

  6. Confirm success. When the provision step completes, the status changes to Installed. The UI watches for these changes live, so the tile and the Installed section refresh automatically, with no manual reload.

    Expected result: the extension appears in the Installed section and its tile shows an installed state.

Live status, no refresh needed

You do not have to reload the app to track progress. As the backend advances the status from Installing to Provisioning to Installed, the tile and detail window update in place. If an operation does fail, the status is set to Failed and the reason is surfaced in the error banner at the top of the app.

If an install seems stuck

A single extension operation has a time limit, so the UI surfaces an error rather than hanging silently if it does not finish. Interrupted operations are cleared automatically once things settle. Wait a moment, then re-open the detail window before retrying.

Optional: install a community extension

Not every extension lives in the official catalog. To install one from a git repository:

  1. Click Add from URL in the hero header.
  2. Paste the HTTPS git URL of the extension repository.
  3. Optionally specify a branch, tag, or commit reference.
  4. Acknowledge the security warning, then click Install.

The originating git URL is recorded against the installed extension, so you can always see where it came from. Because community extensions are not part of the catalog, the UI presents them in the Installed list alongside catalog extensions.

Community extensions are unverified

Community extensions are not reviewed by ControlBird. They can add configuration and run setup scripts with platform privileges. Install only from repositories you have personally reviewed. Any bundled README.md is sanitized before display precisely because the source is untrusted.

Updating and uninstalling

Managing the lifecycle of an installed extension happens from the same detail window:

  • Update: when a newer catalog version exists, the tile flags that an update is available. Open the detail window and click Update to v{newer-version}. The platform replaces the installed version with the new one.
  • Uninstall: open the detail window, click the Uninstall button, and confirm. Everything the extension added is removed for a clean uninstall.
  • Refresh: click the Refresh button to reload the catalog from the API and re-check for available updates.

Uninstalling a dependency cascades

If you uninstall an extension that others depend on (for example, removing mqtt-service while esphome is still installed), a confirmation dialog lists every dependent. Confirming removes the parent and all dependents together atomically. To keep dependents working, leave the shared dependency in place.

Next steps

You have installed, updated, and learned how to remove an extension. From here: