Install and manage plugins

What it does

A plugin arrives as a signed ZIP package, and every plugin is written, developed, and shipped exclusively by Speednet. You install it once for your user account, then enable it per project from the Desktop app or the CLI. Browse what’s available on the plugin catalog before you start.

What it consists of

Installing extracts the signed package to ~/.speedwave/plugins/<slug>/. If the plugin is an MCP service, Speedwave also builds its container image from the package; a resource-only plugin has no image to build and skips that step entirely. Speedwave keeps a separate state folder at ~/.speedwave/plugin-state/<slug>/, where it leaves a marker if that image build fails.

How it works

Run the install command with the path to the package:

Terminal

speedwave plugin install ./my-plugin.zip

1. Speedwave verifies the package’s Ed25519 signature and validates its manifest. This is the same check described in Binary authenticity: only a package signed with the right key gets past this step.
2. It extracts the plugin to ~/.speedwave/plugins/<slug>/.
3. If the plugin is an MCP service, Speedwave builds its container image. A resource-only plugin has no image to build and skips this step entirely.
4. Speedwave registers the plugin.

Before any of that runs, the Desktop install overlay peeks at the ZIP to show the plugin’s name and whether it declares an MCP service (the signal for a container build), without verifying the signature or extracting to a permanent location. The real install still re-verifies the signature from scratch.

The command reports these phases as verifying, extracting, and building, and exits 0 either way:

• Installed: the plugin is on disk and, for an MCP plugin, its image built. Speedwave prints Plugin '<name>' (<slug>) installed successfully.
• Installed with a deferred build: the image build failed, for example from a network outage or a broken Containerfile. Speedwave prints Plugin '<name>' (<slug>) installed; image build failed and will retry on next launch to stderr instead.

A deferred build still exits 0

Check for the stderr message above, or for the marker file ~/.speedwave/plugin-state/<slug>/image_pending, to tell the two outcomes apart. Speedwave retries the build automatically the next time it starts, so you don’t need to do anything unless the build keeps failing.

Enable the plugin for a project with:

Terminal

speedwave plugin enable <service_id> --project my-project

Enabling requires a verified plugin, and it fails if the plugin’s files no longer match what was signed. Reinstalling a signed package clears that.

Set it up

Desktop

1. Open Plugins in the left nav rail.
2. Click $ install plugin and pick the signed .zip package.
3. Once it appears in the list as signed (✓ ed25519), flip its toggle on for the project.

Installed plugins $ install plugin my my-project

plugintypesignedon

figmamcp✓ ed25519

glpimcp✓ ed25519

CLI

1. Install the package: speedwave plugin install ./my-plugin.zip.
2. Enable it for a project: speedwave plugin enable <service_id> --project my-project.
3. Check what’s installed at any time with speedwave plugin list, which shows each entry’s name and version with a [verified] or [UNVERIFIED: <reason>] marker. list skips the startup signature audit, so it keeps working even while that audit is failing for another plugin.
4. Remove a plugin with speedwave plugin remove my-plugin. This deletes ~/.speedwave/plugins/<slug>/ and its sibling state folder ~/.speedwave/plugin-state/<slug>/. It does not delete the project credentials you entered for the plugin or its config entries: clean those up from the Desktop app, or delete the token folders yourself.

Changelog tab

If a verified plugin’s package ships a CHANGELOG.md, its plugin details in Desktop show a Changelog tab alongside the rest, so you can check what changed before you update. The changelog is covered by the same signature as the rest of the package, and the tab only appears once the plugin is verified: an unverified plugin shows no changelog, even if the package contains one.

Security boundaries

Speedwave audits every installed plugin’s signature before running most CLI commands, and a package that no longer matches what was signed makes the command exit 2 until you reinstall it or remove it.

plugin install, plugin list, and plugin remove are exempt from that startup audit, since they’re the commands you reach for to fix a plugin that’s failing it. remove works even on a plugin that fails signature verification, which makes it the way to recover from a tampered install.