Documentation

The best path, chosen and maintained on its own

A VIGIL connection is established immediately through a blind relay, then races in the background toward a direct path between the two machines. When the direct path is ready, the session switches to it without a new handshake; if the network changes — new address, moving from Wi-Fi to 5G, a link going down — the session survives and re-establishes itself on the best available path. The relay, for its part, doesn't go away: it stays on warm standby, ready to take the traffic back if the direct path degrades.

Three roles share the work

Path selection relies on the same distribution of roles as the rest of the mesh, described in detail in the page dedicated to the network. We recall it here because it conditions everything that follows:

The node

The machine itself. It encrypts and decrypts its own traffic end to end, tests the possible paths toward its peers and decides which one to take.

The blind vigie

The relay. It carries encrypted bytes between two nodes without ever reading them: the immediate connection goes through it, and it is what stays on standby.

The controller

The orchestrator. It distributes the signed network map — identities, access policy, relay directory — but never touches the content of the flows.

None of these roles needs an open inbound port on the nodes. The mesh network page details how these three roles fit together; the essential point here is that the vigie relays without reading and that the node keeps control over path selection.

Immediate connection, then the race toward the direct path

The order of operations is deliberate: first a connection that works right away, then the search for the best path. The user never waits for the direct negotiation to succeed before starting to work.

1
Immediate establishment through the relayAs soon as a node wants to reach a peer, the session opens through a blind vigie. Since neither node needs an inbound port, this path is available even behind two strict NATs. Traffic flows, encrypted end to end.
2
Direct-path discovery in the backgroundIn parallel, the two nodes exchange their candidate addresses and attempt to establish a direct path — including through NAT hole punching. The user notices nothing: the relayed session keeps carrying the traffic.
3
Switch to the direct path once it is provenA direct path is only retained once it actually carries validated packets. The session then moves onto it, with no visible interruption of the application flow.
4
Automatic fallback if the direct path failsIf the direct path fails to establish or gets cut, nothing bad happens: the traffic stays on — or returns to — the relay, which never stopped being available.

This "relay first, direct second" model explains why a VIGIL connection always feels instantaneous: the optimal path is an improvement that arrives on top of an already-working connection, never a precondition.

Migration without a new handshake

A VIGIL session is not tied to a pair of IP addresses. It is identified by a transport-level connection identifier, independent of the underlying address and port. This is what lets it survive changes that classic connections cannot withstand.

IP address change: a laptop that moves from the office Wi-Fi to 5G keeps its session open, with no application-level reconnection.
Network change: leaving one site for another, or switching from a wired link to a mobile one, does not cut the flows in progress.
Path change: moving from the relay to the direct path, or the other way around, happens within the same session — the application layer sees no break.

The migration happens without replaying the cryptographic handshake: the session's keys stay valid while it moves from one path to another. This continuity is what distinguishes a migration from a mere reconnection — a file transfer, a video stream or a remote session carries on instead of starting over from scratch.

The relay stays on warm standby

Going direct doesn't mean closing the relay. The blind vigie that carried the initial connection remains available on warm standby for the whole lifetime of the session: it doesn't have to be renegotiated to take over again.

If the direct path degrades — packet loss, climbing latency, a link going down — the traffic can go back through the relay without perceptible interruption.
The relay always carries end-to-end encrypted bytes: whether it serves for establishment, as backup or permanently, it never reads anything.
When conditions become favorable again, the session can race toward a direct path once more — the "relay first, direct second" logic replays continuously.