Skip to main content
Version: v2

Plugins

Host plugins extend hosts with additional capabilities.​

Plugins provide capabilities at the host level, extending a wasmCloud host with specific implementations of interfaces. Each plugin implements a WIT world—a collection of imports and exports that are directly linked to workloads at runtime.

Plugins allow you to customize how your host handles common operations like HTTP requests, key-value storage, configuration, and logging. You can use the built-in plugins provided by wash-runtime, or implement custom plugins for specialized requirements.

wasmCloud supports two kinds of host plugin:

  • Native host plugins — Rust code linked into the host binary that implements the HostPlugin trait. Native host plugins are appropriate for capabilities that need direct host resources (filesystem, network, hardware) or must run with the host's privileges.
  • Host component plugins — WebAssembly components deployed alongside workloads, running as trigger services with a capability ingress. Host component plugins are useful when a capability can be implemented in Wasm and you want to ship, version, and sandbox it like any other component.

Both kinds of plugin provide interfaces to workloads, and a workload does not know whether a given capability is implemented natively or as a component.

Native host plugins​

Native host plugins are Rust implementations of the HostPlugin trait, linked into the host binary at compile time. They run with the host's privileges and can bridge to any resource the host process has access to.

Built-in plugins​

The wash-runtime crate includes built-in plugins for common WASI interfaces. These plugins come in two variants: in-memory implementations for local development (used by wash dev), and NATS-backed implementations for production deployments.

PluginInterfaceDescription
Key-Valuewasi:keyvalueKey-value storage operations
Blobstorewasi:blobstoreBlob/object storage operations
Configwasi:configRuntime configuration access
Loggingwasi:loggingStructured logging output
OpenTelemetrywasi:otelTraces, metrics, and logs export
Messagingwasmcloud:messagingMessage passing and pub/sub communication
Postgreswasmcloud:postgresDirect PostgreSQL access: queries and prepared statements
note

HTTP is handled by the Ingress server (named HttpServer before wasmCloud 2.6.1), which implements the HostHandler trait and is registered separately via with_http_handler() rather than with_plugin(). In addition, all WASI P2 interfaces provided by wasmtime-wasi—including wasi:filesystem, wasi:clocks, wasi:random, wasi:io, wasi:sockets, and the wasi:cli suite—are built into the host core and always available without registration.

Messaging is always available. The remaining plugins are controlled by Cargo feature flags when building your host; the ones above are all in the default feature set, so to trim the set, disable default features and re-enable only what you need (note that the defaults also include features like washlet, wasi-otel, and wasmcloud-postgres, which this drops too). Build against the Git repository — the wash-runtime crate on crates.io is a stale early snapshot that predates the current API:

toml
[dependencies]
wash-runtime = { git = "https://github.com/wasmCloud/wasmCloud", tag = "v2.6.1", default-features = false, features = ["wasi-keyvalue", "wasi-config", "wasi-logging", "wasi-blobstore"] }

Registering plugins with the host​

Native plugins are registered with the host using the HostBuilder API. HTTP is handled separately via with_http_handler() because the Ingress server implements the HostHandler trait rather than HostPlugin:

rust
let host = HostBuilder::new()
    .with_engine(engine)
    .with_http_handler(Arc::new(http_handler))
    .with_plugin(Arc::new(config_plugin))?
    .build()?;

See the runtime overview for a full working example including engine setup and workload start.

Default behavior

If a handler is not provided for a particular capability, a "deny all" implementation is used. This ensures that components cannot access capabilities unless explicitly configured.

Custom native plugins​

You can create custom native plugins by implementing the HostPlugin trait. See Creating Host Plugins for more information.

Custom native plugins are useful when you need to:

  • Integrate with proprietary systems: Connect components to internal APIs, databases, or services that don't have standard WASI interfaces.
  • Add security layers: Implement custom authentication, authorization, or audit logging for capability access.
  • Provide specialized hardware access: Expose GPUs or other specialized hardware to components.

Host component plugins​

A host component plugin is a WebAssembly component that provides a host capability to workloads. Instead of linking a Rust HostPlugin implementation into the host binary, you build the capability as a Wasm component, declare it in host configuration, and the host loads it at startup, without requiring a host rebuild.

Host component plugins run as trigger services with a capability ingress: a single long-lived plugin instance is pinned in the host, and other workloads' capability calls (for example, a wasmcloud:messaging/consumer.publish invocation) are dispatched to that pinned instance across a store boundary. See Trigger services for the cross-store dispatch model.

When to use host component plugins​

Host component plugins are suitable when:

  • The capability can be implemented in Wasm (e.g., no direct OS-level access is required.)
  • You want to ship, version, or sandbox the capability using the same primitives as any other component.
  • You want to iterate on the capability independently of the host binary.

Native host plugins remain the right choice when the capability needs direct host resources (raw sockets, filesystem paths, hardware) or must run with host privileges outside the sandbox. See Plugin or Service? for a full decision guide.

The wasmcloud:host interface​

Host component plugins can import wasmcloud:host@0.1.0 to observe and cooperate with their runtime environment:

  • wasmcloud:host/identity: query the workload and component identifiers of the caller currently invoking this plugin. This allows a plugin to partition state for each caller (e.g., keep one connection or session per workload without callers seeing each other's state).
  • wasmcloud:host/cancel: cooperative per-invocation cancellation. A handler can identify its current job, check whether it has been asked to stop, and observe cancellation signals for long-running work.

For details on authoring, packaging, and deploying a host component plugin, see Creating host component plugins.

Feature-gated​

Host component plugins shipped in wasmCloud 2.6.0. Support is opt-in: release images are built with default features, so enable the host-component-plugins Cargo feature when building a host. If you embed wash-runtime, enable the feature on a Git dependency (the crate on crates.io is a stale early snapshot that predates the current API):

toml
[dependencies]
wash-runtime = { git = "https://github.com/wasmCloud/wasmCloud", tag = "v2.6.1", features = ["host-component-plugins"] }

On Kubernetes, build a custom host image — the source Dockerfile takes CARGO_FEATURES=host-component-plugins as a build arg — and point the Helm chart at your image via the runtime.image values (registry, repository, and tag).

Keep reading​