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.

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.

Plugin	Interface	Description
Key-Value	wasi:keyvalue	Key-value storage operations
Blobstore	wasi:blobstore	Blob/object storage operations
Config	wasi:config	Runtime configuration access
Logging	wasi:logging	Structured logging output
Messaging	wasmcloud:messaging	Message passing and pub/sub communication

note

HTTP is handled by HttpServer, 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 can be enabled or disabled via Cargo feature flags when building your host:

toml

[dependencies]
wash-runtime = { version = "*", features = ["wasi-keyvalue", "wasi-config", "wasi-logging", "wasi-blobstore"] }

Using plugins

Plugins are registered with the host using the HostBuilder API. HTTP is handled separately via with_http_handler() because HttpServer implements the HostHandler trait rather than HostPlugin. The following example demonstrates how to configure a host with an HTTP handler and a configuration plugin:

rust

use std::sync::Arc;
use std::collections::HashMap;

use wash_runtime::{
    engine::Engine,
    host::{HostBuilder, HostApi, http::{HttpServer, DevRouter}},
    plugin::wasi_config::DynamicConfig,
    types::{WorkloadStartRequest, Workload},
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create a Wasmtime engine
    let engine = Engine::builder().build()?;

    // Configure HTTP handler and plugins
    // DevRouter routes all requests to the most recently resolved workload
    let http_handler = HttpServer::new(DevRouter::default(), "127.0.0.1:8080".parse()?).await?;
    let config_plugin = DynamicConfig::new(false);

    // Build and start the host
    let host = HostBuilder::new()
        .with_engine(engine)
        .with_http_handler(Arc::new(http_handler))
        .with_plugin(Arc::new(config_plugin))?
        .build()?;

    let host = host.start().await?;

    // Start a workload (components will have access to plugin capabilities)
    let req = WorkloadStartRequest {
        workload_id: uuid::Uuid::new_v4().to_string(),
        workload: Workload {
            namespace: "example".to_string(),
            name: "my-workload".to_string(),
            annotations: HashMap::new(),
            service: None,
            components: vec![],
            host_interfaces: vec![],
            volumes: vec![],
        },
    };

    host.workload_start(req).await?;

    Ok(())
}

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 plugins

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

Custom 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.

Keep reading

• Learn more about the wasmCloud runtime.
• See the wash-runtime source code for implementation details.
• Watch a discussion of host plugin implementation from a wasmCloud community call.