Runtime

wasmCloud's runtime (wash-runtime) is a simple, flexible runtime environment for WebAssembly workloads.

wash-runtime is a Rust crate that includes Wasmtime as the underlying runtime engine, as well as the wasmCloud host, which serves as a runtime environment for WebAssembly components. A plugin system allows for extension of the host with new and custom capabilities.

The runtime provides easy-to-use abstractions over the low-level Wasmtime API, as well as wasmCloud-specific APIs for managing workloads, handling NATS subscriptions, managing and utilizing host plugins, and more.

For a step-by-step guide to embedding the runtime, see Building Custom Hosts. To run a cluster-connected host managed by the operator, see Cluster Hosts (Washlet). To extend a host with new capabilities, see Creating Host Plugins.

Architecture

The runtime provides three primary abstractions:

1. Engine: Wasmtime configuration and component compilation
2. Host: Runtime environment with plugin management
3. Workload: High-level API for managing component lifecycles

WASI Interface Support

The runtime provides WASI interface support through three distinct mechanisms:

Built-in via wasmtime-wasi (always available, no registration needed): all WASI P2 interfaces including wasi:filesystem, wasi:clocks, wasi:random, wasi:io, wasi:sockets, and the wasi:cli suite.

HTTP handler (HttpServer, registered via with_http_handler()): wasi:http — HTTP client and server. Uses the HostHandler trait, not HostPlugin.

Host plugins (registered via with_plugin(), feature-flag controlled): two sets are included — in-memory implementations for development with wash dev, and NATS-backed implementations for production. Supported interfaces:

• wasi:keyvalue
• wasi:blobstore
• wasi:config
• wasi:logging
• wasmcloud:messaging

Hosts can be extended with additional custom plugins at build-time.

Usage

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
    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
    let req = WorkloadStartRequest {
        workload_id: uuid::Uuid::new_v4().to_string(),
        workload: Workload {
            namespace: "test".to_string(),
            name: "test-workload".to_string(),
            annotations: HashMap::new(),
            service: None,
            components: vec![],
            host_interfaces: vec![],
            volumes: vec![],
        },
    };

    host.workload_start(req).await?;

    Ok(())
}

cargo Features

The crate supports the following cargo features:

• wasi-config (default): Runtime configuration interface
• wasi-logging (default): Logging interface
• wasi-blobstore (default): Blob/object storage interface
• wasi-keyvalue (default): Key-value storage interface
• wasmcloud-postgres (default): PostgreSQL-backed implementations for keyvalue and blobstore
• washlet (default): Washlet support (depends on oci)
• wasi-webgpu: WebGPU interface
• oci: OCI registry integration for pulling components