Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mikronita/mikrom/llms.txt

Use this file to discover all available pages before exploring further.

mikrom-network is the mesh networking service for Mikrom. It establishes and maintains a WireGuard overlay network that spans every worker node, platform service, and database VM in the cluster. Worker nodes register their identity over NATS, and mikrom-network synchronises peer state, routes, and cryptographic keys across all participants. The IPv6 addresses assigned by the mesh are the primary addressing scheme used throughout the platform—from workload traffic routing in mikrom-router to internal name resolution in mikrom-dns.

​
Responsibilities

Mesh Orchestration

Manages WireGuard peer configuration across all nodes. Adds and removes peers as workers join or leave the cluster.

Key Handling

Generates and distributes WireGuard public keys. Maintains cryptographic identity material in the configured data directory.

Route Synchronisation

Keeps routes consistent across all mesh participants. Reacts to NATS events when topology changes.

Host Identity Coordination

Each node is identified by MIKROM_HOST_ID. The network service uses this identity to register the node and coordinate peer discovery.

​
How It Works

1

Worker registers via NATS

When a worker node starts, mikrom-agent and mikrom-network publish the node’s identity and WireGuard public key to the NATS coordination channel.
2

Peer state reconciled

mikrom-network receives the registration event and updates the WireGuard peer list on all participating nodes, establishing encrypted tunnels between them.
3

IPv6 address assigned

The mesh assigns each node an IPv6 address in the fd00::/8 range. This address is used by platform services, routing rules, and DNS records.
4

Routes propagated

Route information is synchronised over NATS so every node in the mesh can reach every other node and the workloads running on them.

​
IPv6 Addressing

The platform uses IPv6 internally across all services. WireGuard mesh addresses are allocated from the fd00::/8 private range. 
Mesh participants (examples):
  mikrom-api      →  fd00::3bc2:7b88:289:62e6
  mikrom-router   →  fd00::28fb:f0bf:d8d1:183e
  worker-node-01  →  fd00::<node-specific suffix>
  app microVM     →  fd00::<vm-specific suffix>
IPv6 mesh addresses assigned by mikrom-network feed directly into DNS records managed by mikrom-dns. Internal service names in the *.mikrom.internal. namespace resolve to these WireGuard addresses.

​
Relationship with Other Services

ServiceDependency on mikrom-network
mikrom-routerUses WireGuard to reach app microVMs. All proxied traffic travels through the mesh.
mikrom-dnsConsumes mesh IPv6 addresses to populate n.mikrom.internal. and u.mikrom.internal. DNS zones.
mikrom-agentRuns alongside mikrom-network on every worker node. The agent relies on the mesh for control-plane connectivity.

​
Configuration

VariableDefaultDescription
MIKROM_HOST_IDrequiredUnique identity for this network node
NATS_URLnats://[::1]:4222NATS server URL for peer coordination
MIKROM_DATA_DIR/var/lib/mikrom-networkDirectory for persistent key material and state
MIKROM_WG_PORT51823WireGuard UDP listen port
MIKROM_ADVERTISE_ADDRESS—Optional external address to advertise to peers
MIKROM_NETWORK_NATS_CONNECT_TIMEOUT_SECS5Timeout for the initial NATS connection
mikrom-network requires CAP_NET_ADMIN to manage WireGuard interfaces. On systemd deployments, ensure the unit has the appropriate capability set before starting the service.

​
Debian Package

A Debian package is available for deploying mikrom-network on production nodes. 
make deb-network   # Build the .deb for mikrom-network

​
Local Development

cargo run -p mikrom-network
cargo nextest run -p mikrom-network
During local development with make up-full, the WireGuard mesh is handled automatically. You only need to run mikrom-network explicitly when testing network topology changes or peer registration flows.

Build docs developers (and LLMs) love

Get started for freeTalk to us