CONCEPTS

Architecture

How the four runtime services — zmesh, zrms, zrun, zbase — fit together to make a Samoza cluster.

A Samoza cluster is one or more zhosts that mesh together. Each zhost runs a small set of cooperating services. Together they form a distributed runtime for WebAssembly Spaces with automatic placement, failure detection, and recovery.

The four services

ServiceRoleDefault port
zmesh-controlplaneCentral registry — zhost membership, super-node election9000
zmeshPer-host P2P agent — connections, message routing, space registry9200
zrmsResource manager — topology placement, heartbeats, failure recovery7331
zrunExecution engine — instantiates and runs WASM Spaces8080

Plus zbase, the service registry (7071), used by all of the above.

How they’re arranged

┌─────────────────────────────────────────────────────────────────────────┐
│                           Control Plane                                  │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                    zmesh-controlplane                            │    │
│  │  - Zhost registry (SQLite or Postgres)                          │    │
│  │  - Super node election                                          │    │
│  │  - Cluster membership                                           │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
┌──────────────────────────────────┐  ┌──────────────────────────────────┐
│         zhost-a (Super)          │  │         zhost-b (Local)          │
│  ┌────────────────────────────┐  │  │  ┌────────────────────────────┐  │
│  │          zmesh             │◄─┼──┼─►│          zmesh             │  │
│  │  - P2P mesh networking     │  │  │  │  - P2P mesh networking     │  │
│  │  - Message routing         │  │  │  │  - Super node connection   │  │
│  │  - Space registry          │  │  │  │                            │  │
│  └────────────────────────────┘  │  │  └────────────────────────────┘  │
│              │                   │  │              │                   │
│  ┌────────────────────────────┐  │  │  ┌────────────────────────────┐  │
│  │     zrms (super mode)      │  │  │  │     zrms (local mode)      │  │
│  │  - ClusterManager          │◄─┼──┼──│  - ResourceTracker         │  │
│  │  - RecoveryManager         │  │  │  │  - Heartbeat sender        │  │
│  │  - Topology placement      │  │  │  │                            │  │
│  └────────────────────────────┘  │  │  └────────────────────────────┘  │
│              │                   │  │              │                   │
│  ┌────────────────────────────┐  │  │  ┌────────────────────────────┐  │
│  │          zrun              │  │  │  │          zrun              │  │
│  │  - Wasm execution          │  │  │  │  - Wasm execution          │  │
│  │  - Space lifecycle         │  │  │  │  - Space lifecycle         │  │
│  └────────────────────────────┘  │  │  └────────────────────────────┘  │
└──────────────────────────────────┘  └──────────────────────────────────┘

The control plane is the central point of coordination — every zhost registers with it on startup, learns who its super node is, and joins the cluster from there. The super node coordinates the cluster (collects heartbeats, decides placement). Local nodes run workloads.

Zhost roles

ConceptDescription
ZhostA physical or virtual host running the Samoza stack.
Super nodeA zhost that coordinates cluster operations and receives heartbeats.
Local nodeA regular zhost that reports to a super node.
SpaceA WebAssembly process managed by zrun.
TopologyA collection of spaces and the paths between them.

A small cluster has one super node and several locals. Larger clusters can elect multiple supers for resilience. The control plane sits above the supers and is the single source of truth for membership.

Four flows that matter

1 · Zhost registration

A new zhost starts, its zmesh connects to the control plane, registers, and learns its assigned super node. From that point on it’s part of the cluster.

2 · Heartbeats

Every local node’s zrms sends a zrms.resource_report heartbeat through zmesh to its super node every 10 seconds. The super node updates a lastHeartbeat table.

3 · Failure detection

If heartbeats stop arriving for ~30 seconds, the super node’s ClusterManager calls failureCallback(zhost). The RecoveryManager marks the zhost unavailable, finds affected topologies, and re-places them excluding the failed zhost.

4 · Cross-host message routing

A space on zhost-a wants to send to a space on zhost-b. zrun-a calls zmesh-a POST /v1/spaces/send. zmesh-a looks up the destination space in its registry, finds it’s remote, forwards the message via the P2P connection to zmesh-b, which delivers it to zrun-b.

Why split it this way

Each service has one concern.

  • zmesh-controlplane is just membership — small, easy to make highly available.
  • zmesh is just transport — keeps zhosts talking, knows who’s where.
  • zrms is just placement and recovery — decides where things should run, notices when they don’t.
  • zrun is just execution — sandbox, lifecycle, ABI provisioning.

Splitting them lets each scale independently and lets you reason about failures cleanly. A zmesh outage doesn’t take down zrun; a zrms outage doesn’t lose work; a zrun outage triggers re-placement, not cluster collapse.

Where to go next