# Plugin mechanism

A [plugin](/docs/plugins/) is a signed ZIP package, and Speedwave never assumes a signature checked once at install still holds later. It rechecks that signature on every path that reads a plugin's files: container setup, image build, resource mounting, the UI listing, and the startup audit.

## Verification and file integrity

The verifier computes a SHA-256 digest over every file in the plugin's folder, except the signature file itself, then checks an Ed25519 signature against that digest with a Speednet public key built into Speedwave. Only Speednet signs plugins, so community contributions go through Speednet for signing rather than being signed directly. Changing one byte of any file changes the digest, and a tampered plugin fails this check before Speedwave runs anything from it.

A plugin's installed folder must never change after install, or its digest stops matching. Speedwave splits a plugin's files into a signed folder, covered by the digest, holding the manifest, the `Containerfile` for plugins that run a worker, and any skills, commands, agents, and hooks; and a separate mutable folder for state that legitimately changes later, such as a pending-build marker.

## Plugin types and image builds

A plugin's manifest decides its type. An MCP service plugin ships a `Containerfile` and runs a containerized worker, optionally alongside skills, commands, agents, or hooks. A resource-only plugin ships none of that, only skills, commands, agents, and hooks for Claude to use directly.

A plugin ZIP holds source code, not a pre-built image. Installing a plugin builds a local image from the verified source, the same way Speedwave builds its own built-in workers. This can take a few minutes; if it fails, the plugin stays installed and Speedwave retries the build on the next launch instead of asking you to reinstall.

## Startup audit and reaching a session

At startup, Speedwave checks every installed plugin's signature and blocks with a list of failing plugins and their reasons if any fail. Listing, removing, and reinstalling a plugin all stay reachable from the CLI even during a blocked startup.

Once a plugin passes verification, it extends a session in one of two ways: an MCP service plugin's container joins as a worker Claude can call through [the tool gateway](/docs/under-the-hood/tool-gateway/), or a resource-only plugin's skills, commands, agents, and hooks become available to Claude directly, with no container involved. A plugin's worker holds no long-lived credentials itself; any OAuth token it needs comes from the host rather than the plugin's files.

## Host bridges for plugins

A manifest can declare a [host bridge](/docs/under-the-hood/workers/#host-bridges-the-narrow-path-back-to-your-machine), the way the [Figma plugin](/docs/plugins/catalog/figma/) reaches its Figma Desktop companion. Speedwave starts one for every verified, installed plugin that declares it, always on and idle on its loopback port when you disable the plugin, and respawns it on install or remove. Defaults, unless the manifest overrides them: 1 MiB max frame size, a 300 second pairing timeout.

The plugin's detail page shows this as a connection card: a read-only Connect URL, a masked Token with reveal and copy, and a status dot for connected, companion connected and waiting on the worker, or waiting for connection.

See [using plugins](/docs/plugins/using-plugins/) for installing and enabling a plugin, and [writing a plugin](/docs/plugins/writing-a-plugin/) for building and signing one.