Plugins

A plugin adds a service to your stack that lemonfiber does not ship. It is data: one plugin.toml describing a service, what it can be relied on to do, how the stack reaches it, and what must be true before it counts as installed. It contributes no code to lemonfiber’s own process.

lemonfiber writes the container. A manifest names an image pinned to its digest, a port and whether that port is for this machine or your network, and whether the service needs your media library mounted. The Compose entry, the proxy address and the dashboard link are generated from that, and there is no field in which a plugin could ask for more — no environment, no devices, no kernel capabilities, no network mode, no fragment of Compose. A service that needs any of that cannot be a plugin; fork the stack with --stack-dir instead. The reasoning is ADR-0021.

A plugin adds and never overrides. A check it contributes to the doctor runs beside the bundled ones under the plugin’s own name, and cannot replace, reorder or silence one of them. It gets no dashboard panel and no command of its own, and a remedy it offers is shown to you, never run.

Nothing is installed half-way. A manifest with anything wrong in it is refused whole, with every fault listed at once; an install whose own proofs or whose effect on the stack’s checks do not hold is put back.

What is built, and what is not

Everything on this section describes the lemonfiber revision this site pins, which is ahead of every release. At that revision:

• Built: installing a plugin from a directory on this machine, or from a git repository at the one commit a branch, tag or commit resolves to; updating one from any source an install takes; listing and removing one; the offer each of those makes before it acts, and approving each value a recipe would send elsewhere; the proofs and the stack’s own checks that gate an install, and the reversal when either fails; contributed doctor checks and remedies; capability wiring and choosing what fills one; the author’s reads and plugin provenance.
• Not built: the key the catalogue’s index is signed with. Installing by name resolves through that index only once its signature verifies, and this build carries no key to verify it with, so every install by name is refused and every install is recorded as unreviewed. Recipes can be declared and checked but are refused, because this build offers a plugin nothing that would run one. Of what a manifest may ask for in [requires], this build offers only what its extension points need — the names printed there under a plugin declares — and refuses any other. In practice a plugin that only adds doctor checks installs, and a plugin that adds a service — every plugin in the catalogue today — is refused.

The roadmap says which version carries the rest.

Installing a pluginAsk for an offer, install, update and remove one, and what each step checks before it counts.

Capabilities and wiringHow the stack asks for what a service does rather than for the service, and how to choose which one answers.

The manifestEvery field of plugin.toml, read out of the schema the binary validates against.

Extension pointsThe places a plugin may add a row to lemonfiber itself, and the rules each row keeps.

Writing a pluginFrom the template to a manifest whose claims are proved, and on to the catalogue.

Trust and provenanceDigests, signatures, where every value came from, and what a plugin may never do.

The plugin templateThe repository a plugin starts from, rendered from the author's guide it carries.

The plugin catalogueWhere published plugins are registered, and what a registration is checked against.

Where to go next

Every flag of every plugin word is in the command reference, and what each refusal means is on the PLUGIN codes page. What lemonfiber plugin installed --json returns is the plugins kind in the API. The requirements this section describes are F3 to F11 in the specification, and how the core is put together behind them is the architecture notes.