Skip to content

Plugins

Everything Sowel connects to -- and every automation recipe it runs -- comes as a plugin. A fresh Sowel install has zero plugins: you pick the integrations and recipes you need from the store, and only those run on your instance.

Plugins are managed from Administration > Plugins (admin only).

The two tabs

Installed lists what runs on your instance:

  • Integrations show their connection status and how many devices they feed. Selecting one opens its details, where you can disable, re-enable, update or uninstall it.
  • Recipes are the automation templates available when you create recipe instances.

Store lists what you can install. Entries come from the official Sowel catalogue, plus your own personal sources (see below). The Refresh button re-reads the catalogue immediately, useful right after a new plugin or version is announced.

When a newer version of an installed plugin is available, an update badge appears on its row (and in the topbar updates sheet). Updating keeps all your settings, devices, equipment bindings and history: only the plugin code changes.

When several plugins are behind, a banner above the list updates them all at once. Packages installed from a personal source are named apart in that banner: each one needs its own fingerprint confirmation, so you update those from their own row.

Finding a plugin

The search field above the list filters both tabs as you type. It matches plugin names, descriptions and keywords in the language you are using, and ignores accents -- typing eclairage finds Éclairage. The Integrations / Recipes counters follow the search, so you can see at a glance where the matches are. Click the cross in the field to clear it.

Recipes are grouped by category in both the Installed and Store tabs, so you can scan for what you want to automate instead of reading every card:

Category What you find there
Lighting Switch, motion or state driven lights
Heating and cooling Presence heaters, thermostats, smart cooling
Watering and pool Garden watering, pool pump scheduling
Scheduling Fixed-time or sun-based on/off programs
Safety and monitoring State watchers, runtime guards
Energy and display Presence-driven displays, energy helpers

A recipe without a category -- for example one installed from a personal source -- appears under Other. Integrations are not categorized: they stay a single list, filtered by the same search field.

Trust levels

Every store entry belongs to one of three trust levels, so you always know whose code you are about to run:

Level Badge Who publishes it What Sowel checks
Official none The Sowel maintainer Integrity hash pinned in the official catalogue, code maintained with Sowel itself
Community amber Community A third-party developer Integrity hash pinned in the official catalogue; the code itself is not reviewed by Sowel
Personal blue Personal You (your own GitHub repositories) Integrity hash you approve yourself at install, then pinned (see below)

Installing a community plugin asks for a one-time confirmation. Installing or updating a personal plugin always asks for confirmation, showing exactly what you are about to run.

Personal sources

Personal sources let you install your own plugins and recipes without publishing them to the official catalogue. Typical uses: a recipe you wrote for your own home, or trying out a plugin you are developing before sharing it.

Requirements

A personal source is a public GitHub repository that has at least one release with a sowel-*.tar.gz asset -- the standard Sowel plugin packaging. If you are writing your first recipe, the Recipe Development guide walks through producing exactly that.

Adding a source

  1. Open Administration > Plugins > Store and scroll to Personal sources.
  2. Enter the repository as owner/repo (for example jdoe/sowel-recipe-my-recipe) and click Add.
  3. The source appears in the list with its latest release version. If the repository has no release yet, it is kept with a "no release yet" hint and becomes installable as soon as you publish one.

The plugin then shows up in the store with the blue Personal badge.

Installing: the fingerprint confirmation

When you click Install on a personal plugin, Sowel downloads the release, computes its SHA256 fingerprint, and shows it in a confirmation dialog together with the repository and version.

  • Confirming installs exactly the content matching that fingerprint and pins it. If the file ever changes behind the same version, Sowel refuses it.
  • Every later update shows the same dialog again with the new version and new fingerprint, because the content changed since you last approved it. Nothing updates behind your back.
  • The dialog appears wherever you start the update: the plugin's row, its detail panel, or the updates panel in the top bar. A personal package is marked with its Personal badge there too, so the extra step is no surprise.

You are trusting the repository owner

Nobody reviews the code of a personal plugin. It runs with the same privileges as Sowel itself. Only add repositories you own or fully trust -- the fingerprint guarantees what you install never changes silently, not that the code is safe.

Removing a source

Removing a source does not uninstall plugins already installed from it: they keep running. It only stops future installs and updates from that repository. Re-adding the source later restores updates.

Renaming a repository

A rename is an uninstall and a fresh install, never an update.

GitHub redirects the old name, and that redirect is what makes this quiet: the package installed under the old id keeps finding releases, so it keeps advertising an update. That update can never install — the source list now carries the new name, and Sowel refuses to update a package whose source it no longer holds. It says so on the row.

So: add the renamed source, install it, then uninstall the old package. Recipe instances do not carry over — recreate them, and pin the new instance again if a Dashboard tile pointed at the old one.

For plugin and recipe authors

Want to build one? The technical guides cover the full journey, from scaffolding to publishing:

Once your plugin is worth sharing beyond your own home, the community level is the next step: an entry in the official catalogue, so any Sowel user can install it from the store.