Documentation

How the mesh network works

VIGIL-MESH is a mesh network: each machine talks directly to the others whenever possible, rather than funnelling all traffic through a central server. Three roles share the work — the node, the vigie and the controller — and the infrastructure does nothing but relay encrypted bytes without ever reading them. The connection is established immediately, then switches smoothly to the shortest path, and the session survives network changes: moving from Wi-Fi to 4G breaks nothing.

Three roles, no trust required in the infrastructure

VIGIL-MESH splits the work between three clearly distinct roles, and none of them requires you to place your trust in the infrastructure. The node is your machine: it is symmetric — both client and server — and can even relay traffic for its neighbors when that shortens a path. The vigie is a blind relay doubled with a NAT-traversal coordinator: it forwards encrypted bytes and helps two nodes find each other, without ever reading what goes through. The controller, finally, manages identities, the relay directory and addressing; it distributes the network map, but never sees a single data packet or a single session key.

Actor	What it sees	What it never sees
The vigie	Opaque flow and group identifiers, sizes, cadence and IP addresses	The content, the session keys, the network map in clear text
The controller	Identities, the access policy, the relay directory	The content of your flows — an end-to-end session, like any peer
A peer node	Only what the access policy allows	The private keys of the other nodes

Three separate roles: the node encrypts and decrypts, the vigie relays without reading, the controller distributes the network map without touching the data.

Immediate connection: your data never waits for NAT traversal

Punching through firewalls and NATs takes time, and that time is unpredictable. Rather than keeping your data waiting during the negotiation, VIGIL-MESH first opens a path that is guaranteed to work, then improves it in the background.

1
Session ready right awayWithin the first milliseconds, an end-to-end encrypted QUIC session opens through the best available relay: your data flows without waiting for NAT traversal.
2
The direct-path raceIn parallel, VIGIL-MESH starts the direct-path race: it tests every possible route between the two nodes, with the vigie coordinating NAT traversal to open a direct passage.
3
Seamless migrationAs soon as a direct path is validated and elected as the best one, the session migrates to it with no new handshake and no interruption: in-flight flows don't even notice.
4
The relay stays on warm standbyThe relay doesn't go away: it stays on warm standby, ready to take the traffic back instantly if the direct path degrades or disappears.

The session starts through the relay, then switches to the direct path as soon as it wins the race — without the connection ever being interrupted.

Zero inbound ports to open on the node side

An ordinary node needs no inbound firewall rule. It opens its connections outward, never the other way around: a single outbound infrastructure port is enough to join the mesh and make everything work. Your workstation, your application server or your camera therefore exposes no inbound attack surface.

On the node side: no inbound port to open, no port forwarding to configure on the router or firewall.
A single outbound flow to the infrastructure is enough for all the traffic.
Only the relay role — that is, a vigie — listens for inbound connections; it is the only component that exposes ports.

Stable addresses and locally resolved names

Each machine receives a stable address that doesn't change from one session to the next: an IPv4 taken from the CGNAT space 100.64.0.0/10 and an IPv6 ULA derived from the network's identity. Your applications therefore always find their peers at the same address, whatever the underlying physical network.

Names, in turn, are resolved locally, straight from the signed network map the controller distributes (MagicDNS): no DNS query ever leaves the machine. So nobody outside learns which device is trying to reach which other.

A single connected node is enough for a whole site

Not every machine on a site needs to reach the infrastructure. Thanks to transitive connectivity, it is enough for a single machine on the site to reach a vigie for the whole site to become a member of the mesh: data, control, multicast and even the enrollment of new devices then travel through that node as a local relay.

A single node reaches the vigie: by transitivity, the whole site joins the mesh through it.

Better still: an island cut off from the internet keeps working between its already-verified members. As long as the nodes have authenticated once, they keep exchanging over the local network — in unicast as in multicast — without ever depending on a connection to the outside.

Restrictive networks: the tcp-only profile

Some corporate or hotel networks block all UDP. For those environments, VIGIL-MESH provides a tcp-only compliance profile: in this mode, the node emits no UDP datagram and carries all its traffic over TCP connections. Even multicast remains available: it is reconstructed through a TCP fan-out to each recipient. Local discovery and real-time traffic keep working, at the cost of a little extra latency.