Wruntime

A distributed WASI Preview 2 runtime for building networks of WebAssembly modules. Guests call logical HTTP endpoints such as http://ecommerce.inventory/inventory.InventoryService/GetItems; Wruntime intercepts the call, discovers a healthy module instance, and routes it locally or across nodes.

Note

Wruntime is an experimental, pre-1.0 project built in part through LLM-assisted development. The custom wruntime:* guest WIT APIs may change incompatibly; pin the runtime and SDK versions used by guest modules.

flowchart LR
subgraph data_plane["Streaming data plane"]
caller["Caller WASM"] -->|"logical HTTP"| source_engine["Source wr-engine<br/>WASI HTTP interception"]
source_engine -->|"loopback"| proxy_a["wr-proxy A"]
proxy_a --> route{"Selected instance<br/>location"}
route -->|"local"| local_engine["Local wr-engine"]
route -->|"peer"| proxy_b["wr-proxy B"]
proxy_b -->|"local"| remote_engine["Remote wr-engine"]
local_engine --> destination["Destination WASM"]
remote_engine --> destination
end
subgraph control_plane["Control plane"]
postgres[("Shared PostgreSQL")] <--> managers["Active-active<br/>wr-manager cluster"]
end
proxy_a -.->|"engine registration, readiness,<br/>and deployment identity"| managers
managers -.->|"route sync and scheduled jobs"| proxy_a

Loading

The proxy streams internal and cross-node request and response bodies without buffering. Public ingress is a separate trust boundary: it strips reserved headers, buffers one bounded request body, and transcodes supported protobuf, canonical protobuf JSON, or flat form input to validated protobuf wire bytes.

Scope

Wruntime currently provides:

• logical service discovery, semantic-version routing, load balancing, circuit breaking, and OpenTelemetry tracing;
• multi-node peer routing over mTLS and active-active managers with PostgreSQL persistence and lease-based liveness;
• protobuf service modules plus durable, at-least-once workers and schedules;
• optional public ingress with request transcoding, schema validation, and deny-by-default, allowlisted external HTTP egress;
• guest capabilities for PostgreSQL, S3-compatible blob storage, tracing, Anthropic Claude, namespace-scoped secrets/environment values, and ephemeral scratch filesystems;
• systemd and Docker deployment bundles, exact-revision readiness checks, retained-release rollback, and coherent cluster status.

See Architecture for the full request and control-plane flows.

Quick start

A source checkout requires:

• stable Rust and Cargo;
• just, protoc, and Python 3;
• the wasm32-wasip2 Rust target and wasm-tools;
• Docker with Compose for PostgreSQL, RustFS, and local observability services;
• OpenSSL for local example secrets.

rustup target add wasm32-wasip2
just dev-up
just certs
just multi-node-inline

A successful run sends an Echo request through Node A, across an mTLS peer connection, to a WASM module on Node B. Stop the shared development services with just dev-down. See the multi-node example for the interactive topology and port map.

Build a guest module

Start with the Guest Module Author guide:

• module template — current manifest, WIT world, build script, and validation shape;
• API guide — preferred SDK usage and lifecycle semantics;
• worked examples — production patterns and their supporting configuration.

Exact guest contracts live in wr-sdk/src/, wr-build/src/lib.rs, and root wit/. Prefer the SDK facades and generated protobuf clients over raw WIT bindings unless an operation is not otherwise exposed.

Executable examples

Example	Demonstrates
Ecommerce	Generated client/service calls, PostgreSQL migrations, load balancing, tracing
Stockmarket	Multiple services, persistence, and configurable replicas
Codegen	Workers, LLM, database, blobstore, egress, and scratch filesystem
Multi-node	Cross-node placement and mTLS peer routing

Use just with no arguments to list every build, test, example, and deployment validation recipe. Common maintainer commands are:

just build
just tidy
just test
just test-wasm
just validate-ecommerce

Testing prerequisites and the change-sensitive validation matrix are linked from Testing. To inspect the repository-local CLI, run just cli --help.

Repository map

Path	Purpose
wr-manager/	Active-active registry, routing state, schedules, secrets, and cluster status
wr-proxy/	Local/peer routing, public ingress, egress policy, and circuit breaking
wr-engine/	Wasmtime component execution, host capabilities, workers, and module lifecycle
wr-sdk/, wr-sdk-macros/, wr-build/	Guest SDK, macros, and protobuf service/client generators
wr-cli/	Development, operations, certificate, and deployment CLI
wr-common/, proto/, wit/	Shared Rust types, control-plane protobuf, and guest host ABI
wr-tests/	Integration and WASM host-binding tests
examples/	Executable guest applications and local topologies
docs/	Public guides, references, and contributor workflows

Documentation

• Architecture — topology, trust boundaries, request flow, clustering, workers, and schedules
• Configuration — manager, proxy, engine, module, ingress, egress, and capability configuration
• Module SDK — wr-sdk and wr-build overview
• Host bindings — database, blobstore, tracing, LLM, environment, and filesystem behavior
• Schemas — protobuf descriptors, validation, and RPC paths
• Control-plane and job APIs — manager/node gRPC and worker HTTP RPC contracts
• Deployment — bundles, systemd/Docker lifecycle, mTLS, rollback, and cluster status
• Testing — local infrastructure, focused tests, and full validation
• Contributor modes — guest-module and runtime-maintainer workflows