Architecture Overview

Rizoma Mesh is the private network core of the platform: a self-hosted overlay where identity, policy, and traffic are owned by the operator — not by a public cloud provider.

One network, many services

A Rizoma environment is a private overlay network built from four cooperating roles. The agent opens a TUN interface on each enrolled host, applies routes, advertises endpoints, handles the heartbeat, and moves encrypted packets over QUIC. The coordinator is the control plane: it owns enrollment, the MeshCA trust root, peer records, setup keys, RBAC, ACL distribution, relay inventory, monitoring, snapshots, and the system APIs. Relays keep nodes reachable when direct paths fail, and an ingress exposes selected services to the outside world under operator policy.

Every enrolled node receives an address from the reserved CGNAT range 100.64.0.0/10, assigned as a per-node /32, plus a name under the Magic DNS suffix Rizoma.mesh. The default MTU is 1420 — tuned for QUIC inside the tunnel without fragmenting outer UDP packets.

Reference topology

  Internet
     |
  [ ingress ] &lt;-------- public DNS + TLS
     |                        |
  [ relay ]  &lt;---[ coordinator ]---> MeshCA / ACL / RBAC
     |                        |
  [ agent: node-a.rizoma.mesh ]  -- 100.64.0.1/32
  [ agent: node-b.rizoma.mesh ]  -- 100.64.0.2/32
     |
  [ product services ]  Webpanel | S3 | Git | Router | CMS

The packet path

Traffic between nodes follows five stages: capture on the local interface, resolve the peer's mesh identity and current endpoints, encrypt the payload, transport it over QUIC, and inject it into the destination's TUN device. The receiving agent validates the source identity, decrypts, checks replay state, and injects — so a packet is never trusted because of where it came from, only because of who signed it.

Sessions are established with a hybrid X25519 + ML-KEM-768 key exchange, protecting the tunnel against both current and near-future quantum adversaries. Payloads are protected with AES-GCM, bound to the QUIC connection, and guarded with confirmation tags and replay windows. When a direct path is unavailable, the relay fallback forwards only already-encrypted payloads — a relay can move traffic but never read it.

For environments with special routing needs, the agent supports exit-node routing with route exclusions, NAT, MSS clamping, and leak controls, and optionally accelerates packet paths with AF_XDP/XDP.

Why QUIC. QUIC gives the mesh multiplexing, a TLS transport, streams and datagrams, and firewall-friendly UDP reachability — one path that works across NATs without opening a zoo of TCP ports.

What the coordinator owns

The coordinator is the single source of truth for the environment. It compiles ACLs, teams, groups, and firewall rules into the policy agents actually apply; it distributes peer records, relay selection, and ingress assignments; and it keeps the snapshot and monitoring state that makes day-two operations possible. Coordinator state is stored in SQLite or PostgreSQL: node records, ACLs, relays, ingress resources, events, and snapshots.

The coordinator exposes its REST API under /v1 — auth, nodes, peers, ACLs, relays, ingress, MeshCA, firewall, telemetry, snapshots, monitoring, and WAF — and the dashboard proxies those APIs while serving peer and relay installers.

Product services as capabilities

Every Rizoma product operates inside the mesh as a capability rather than a standalone server:

Webpanel — the mesh hosting control plane: 12 managed services across workloads, network, and communications.
S3 storage — an S3-compatible endpoint reachable only through the mesh, at the node's mesh IP on port 9000.
Rizoma Router — a Linux security gateway that brings WAN/LAN, firewall, NAT, DNS, DHCP, and VPN together for mesh-connected environments.
Rizoma Git — the self-hosted forge: repositories, pull requests, issues, CI/CD custody, signed artifacts, and audit evidence.
Rizoma CMS — publishing inside the perimeter, under the same identity and policy rules.

Because products share the mesh identity, an operator who can read a node's ACL posture can reason about every product attached to it — one control surface instead of per-product silos. The system requirements page covers what a host needs before any of this runs.

Next System Requirements