Overview of GritivaCore gmesh#

GritivaCore gmesh is a WireGuard-based overlay network designed to connect scopes across multiple virtual machines (VMs). Unlike traditional WiFi mesh networks, gmesh operates within the context of scope network namespaces (netns), providing a secure and efficient means of communication between isolated environments.

Key Concepts#

What is gmesh?#

Gmesh utilizes WireGuard to create a secure overlay network that allows different scopes within VMs to communicate seamlessly. Each scope can have a wg-gmesh interface configured inside its netns, enabling direct peer-to-peer connections without a central relay.

Peer State Machine#

The peer state machine in gmesh follows a specific sequence:

1. PEER_STATUS_DISCOVERED
2. PEER_STATUS_CONNECTING
3. PEER_STATUS_CONNECTED

In case of a handshake timeout, the state transitions back to CONNECTING, allowing for retries.

The gmeshd Daemon#

The gmeshd daemon runs on each VM, managing the peer roster and the wg-gmesh interface within each scope netns. It communicates with the control panel for updates and handles key rotation for secure connections.

CLI Commands#

To manage peers and connections, the following CLI commands are essential:

• List peers: gmeshctl peer list
• Remove a peer: gmeshctl peer remove --id <peer_id>
• Connect to a peer: gritivactl scope mesh connect my-app --peer remote-vm:other-scope

Watchdog and Auto-Disconnect#

The mesh watchdog monitors peer connections, retrying update_peer every 60 seconds for peers that are stuck in the CONNECTING state. If the remote scope lacks a wg-gmesh interface, manual cleanup is necessary (see the runbook for details).

Common Failure Mode#

A common issue arises when a scope is missing the wg-gmesh interface within its netns, causing the peer to remain in the CONNECTING state indefinitely. This was identified as the cause in the 2026-05-14 mesh-stuck-peer postmortem.

Conclusion#

GritivaCore gmesh provides a robust solution for connecting isolated environments securely and efficiently. Understanding its architecture and operational commands is crucial for effective management.