Managed Plugins
Sparkrun has bundled plugins, managed Git snapshots, manual plugin directories, and explicitly selected installed Python integrations. Use managed plugins for SparkRoute and ColdSnap; OCI Relay remains bundled. A plugin’s API declaration, its release version, and its Sparkrun compatibility range are separate checks.
Install and manage external plugins
Section titled “Install and manage external plugins”sparkrun plugins add https://github.com/sparksq/sparkrun-sparkroute-pluginsparkrun plugins add https://github.com/sparksq/sparkrun-coldsnap-plugin --enablesparkrun plugins listsparkrun plugins list --jsonsparkrun plugins update sparkroutesparkrun plugins update --allsparkrun plugins rollback sparkroutesparkrun plugins remove sparkrouteplugins alone lists plugins. The hidden setup plugins alias remains available
with identical subcommands. Management commands inspect metadata without loading
plugins, so they can repair an installation whose plugin fails at import. Use
list --check to additionally check managed plugins in a bounded child process.
The state column reports whether the plugin is permitted to load (enabled or disabled).
Compatibility is checked on every listing; it does not imply a successful load.
add asks you to trust the supplied source before executing its code. Plugins
run with your permissions. This grants standing consent to future compatible
updates from that source, including updates during sparkrun update. Use
--trust for explicit noninteractive consent. A general --yes is not a trust
grant. Changes to the source’s declared module, distribution, package path,
repository, or capability require renewed consent.
Adding a plugin enables core.external_plugins if needed. If that would also
activate existing plugins.paths, their activation needs separate confirmation;
noninteractive users must review and enable those paths beforehand. The plugin’s
loading state follows its existing policy unless you pass --enable, which
explicitly enables the plugin. Capability flags retain their configured/default
values. Unknown flags default off. Environment feature overrides and
SPARKRUN_NO_EXTERNAL_PLUGINS still take precedence. Installing ColdSnap does
not trust the recipe registries it declares; use the separate registry trust flow.
Git sources default to main, resolved once to an immutable commit. Select a
branch, tag, or full commit with --ref:
sparkrun plugins add https://github.com/sparksq/sparkrun-sparkroute-plugin --ref mainsparkrun plugins update sparkroute --ref refs/tags/v0.3.3sparkrun plugins add https://github.com/sparksq/sparkrun-coldsnap-plugin --dry-runBranches track new commits even when the plugin’s version string is unchanged.
Tags and commits are pinned. Explicit updates detect moved tags and refuse them;
automatic updates leave pins alone. Ambiguous tag/branch names require a fully
qualified ref. Select managed plugins by their stable name or an unambiguous
saved source URL. Removing needs confirmation (--yes for automation). Dry runs
may fetch metadata but do not trust, execute, activate, or prune plugins.
This release supports Git source snapshots. Wheel/PyPI acquisition is a separate
planned phase. Git installs read existing plugin.toml and pyproject.toml as
data: no custom registry definition and no build backend execution. They require
static project metadata, a pure Python package with a literal
SPARKRUN_PLUGIN_API_VERSION, explicit Python and Sparkrun ranges, and dependencies
already satisfied by the host. Both top-level packages and
sparkrun.plugins.<package> layouts are supported. Symlinks, submodules, compiled
payloads, conflicting providers, and unsupported layouts are rejected. Package
resources and declared license files are preserved.
Enable or disable plugin loading
Section titled “Enable or disable plugin loading”Loading a plugin and enabling one of its capabilities are separate actions:
sparkrun plugins enable sparkroutesparkrun setup features enable gateway.sparkroutesparkrun plugins disable oci-relay --dry-runsparkrun plugins disable oci-relayplugins enable and plugins disable work across bundled, managed, manual, and
installed plugins. Enabling permits registration and runs the plugin’s enable
hook; it preserves capability choices. Disabling prevents the plugin’s imports,
commands, and registrations in new processes, while retaining its installation,
settings, and gateway selection. It does not stop services. Restart long-running
consumers after changing loading policy. Required application plugins cannot be
disabled through these commands.
The commands write canonical plugin IDs under plugins.enabled:
plugins: enabled: sparkroute: true oci-relay: falsefeatures: gateway: true gateway.sparkroute: trueExplicit plugin overrides take precedence over legacy integrations settings,
application-profile selection, and old whole-plugin flags such as
plugins.oci_relay or integration.k8s. Existing settings remain readable as
fallbacks. External plugins still require core.external_plugins, and loader
environment opt-outs still apply. A disabled plugin blocks its capabilities even
if their flags are on.
Explicitly enabling a gateway capability selects that provider in proxy.yaml.
For example, setup features enable gateway.sparkroute selects SparkRoute,
including when that flag was already on. Enabling its plugin alone does not
select it, and a feature command does not enable a disabled parent plugin.
Other gateway capabilities stay enabled. An unavailable selected provider raises
an error; there is no silent fallback. Resetting a feature restores its default
without running an enable hook or selecting a gateway.
Updating Sparkrun and compatibility
Section titled “Updating Sparkrun and compatibility”Both sparkrun update and sparkrun setup update check every plugin’s declared
compatibility, including disabled and unmanaged plugins. By default they update
trusted managed plugins to compatible revisions within their saved source/ref
policy, including repairs for plugins made incompatible by the new core.
sparkrun update # core, compatible managed plugins, registriessparkrun update --no-update-plugins # local plugin audit only; no plugin fetch/writesparkrun setup update --no-update-plugins --no-update-registriesA fresh process checks the resulting core, Python, plugin/profile APIs, and
installed dependency constraints. Incompatible or unknown candidates and failed
load tests leave the active plugin intact. Other plugin updates continue after a
failure. A failed core upgrade exits nonzero, as does a failed explicit
plugins update. Unmanaged plugins are audited but never
modified. Failed core installs or unverifiable resulting identities permit only
an audit, not repairs. An older core without the reconciliation helper reports
that the audit is incomplete.
Updates and rollback preserve plugin loading and capability choices. Updating a disabled plugin does not enable it. Lifecycle hooks can plan configuration changes for explicit actions; startup, inventory, validation, and dry runs never run them. See lifecycle hooks for events, failure handling, and the plugin author contract.
The same compatibility evaluator is used by add, update, rollback, list, and core updates. Ordinary startup performs no new version-range/dependency audit or network update. Existing feature, plugin API, and application-profile guards still apply. Missing declarations are reported as unknown rather than assumed compatible. The opt-out does not check whether an update is available.
Storage and rollback
Section titled “Storage and rollback”Managed plugins live beside the active config file, outside Sparkrun’s Python
environment, under plugins/<name>/<generation>/. plugins.yaml records source
trust, the exact revision, active generation, and ordered previous generations.
Changing or reinstalling Sparkrun does not replace these files. Alternate config
roots keep separate plugin stores.
By default each plugin keeps two generations: current and previous. Configure a
positive integer in config.yaml to change the total retained count:
plugins: retain_generations: 21 disables rollback history. Larger values retain the most recently active
distinct generations. Updates prune only after activation succeeds. Rollback
validates the previous payload and swaps it with current without copying; the
saved source/ref stays unchanged, so a later update may advance it again. Use
update --ref to pin an older revision.
Lowering the limit takes effect across the store at the next successful mutation,
including a no-op update. Listing, dry runs, startup, and --no-update-plugins
never prune. An interrupted activation is recovered by the next mutating command.
If deletion fails after commit, the update reports cleanup pending and blocks
further installation until cleanup succeeds. remove deletes manager-owned
payloads and history even when a plugin cannot load, while preserving capability
flags, runtime data, and user recipe-registry settings. Long-running plugin
consumers should be restarted after replacement, rollback, removal, or pruning;
retained history does not indefinitely preserve files for running processes.
Reading inventory
Section titled “Reading inventory”plugins list inspects metadata without importing plugin code. It shows enabled
plugins by default, including in JSON; add --all for disabled entries. The effective
loading state, actual loaded state, compatibility result, and optional load check
are separate facts. Missing declarations are unknown, not compatible; unknown
versions are JSON null. Read the diagnostics following the table. --check
executes trusted managed plugins in a child process with a 60-second timeout,
for listed entries (including disabled ones with --all); it is not a metadata-only inspection.
The table’s FEATURES column lists declared capability flags, including those of
disabled plugins when --all is used. It does not report whether those capabilities are enabled.
none means there are no separate flags; unavailable means declarations could
not be read. Use setup features list for effective capability state and its
OWNER column. JSON inventory also includes features, state_source,
blocked_reason, and selected_gateway.
Manual directories for development
Section titled “Manual directories for development”For code you control, explicitly enable the external plugin gate and configure paths beside your application config:
plugins: paths: - ~/src/my-sparkrun-pluginssparkrun setup features enable core.external_pluginsModules in these directories execute with your permissions at startup and must
declare SPARKRUN_PLUGIN_API_VERSION = 1. Supported registration failures roll
back enlisted contributions and remain visible in inventory; arbitrary plugin I/O
cannot be undone. Required integration failures and provider conflicts can block
launches. A failed optional import is not proof that every startup can continue.
Installed Python integrations are a different mechanism: installation supplies
metadata, but their stable IDs must be selected before initialization through
plugins enable, plugins.enabled, or the application profile.
See Plugin Development for entry
points, plugin-owned registries, CLI commands and options, recipe extensions,
setup steps, execution providers, benchmarks, and daemon integration examples.
See plugins CLI for flags and Updates for core upgrades. Drain long-lived daemon consumers before changes that would prune their leased generations; see daemon updates.