Documentation

Enroll your first machine

Enrolling a machine means installing the VIGIL-MESH client, then authorizing that device to join your workspace. VIGIL-MESH offers three methods depending on the type of machine: a pre-authorized key for a screenless server, a short-lived invitation for a device operated by a person, or an approval queue when you want to validate every request by hand. In all cases, the machine opens no inbound port.

The three enrollment methods

The choice of method depends mostly on the machine: is it screenless (headless), or operated by a person? The table below sums up the three paths. They all lead to the same result — an active device in your workspace — but they do not offer the same safeguards.

Method	When to use it	Safeguards
Pre-authorized key	Servers and headless machines, automated deployments, images to clone.	Limited use: bounded number of uses and validity period, revocable at any time.
Short-lived invitation	The device of a person you know, one-off commissioning.	A short-lived link or code, restricted in use, that expires on its own.
Approval queue	Environments where every membership must be validated by an administrator.	The machine stays pending until explicit approval in the console; refusal is possible.

Enroll step by step

The sequence is the same whatever the method: install the client, then authorize it. The client takes care of the rest — generating the identity, establishing outbound sessions, receiving the address and the name.

1
Install the clientInstall the VIGIL-MESH client on the machine to connect. See /en/docs/install-windows for Windows and /en/docs/install-linux for Linux (workstations and servers).
2
Prepare the authorizationFrom the console, issue a pre-authorized key for a headless server, generate a short-lived invitation for a workstation, or simply enable the approval queue if you validate by hand.
3
Start the enrollmentOn the machine, start the client with the key or the invitation, or let it file a request in the approval queue. The client then generates its identity and opens its connections outward — no inbound port is opened.
4
Confirm in the consoleThe device appears in the inventory. With the approval queue, approve it; otherwise it becomes active. It receives a stable address and a MagicDNS name, ready to join your networks.

Device lifecycle

An enrolled device is not set in stone: its status evolves over its life in the workspace. These states are read and managed from the console, and they determine whether the machine can communicate on the mesh.

Active: the device is authorized and takes part in the network; it sends and receives traffic according to the access policies.
Suspended: access is paused, without deleting the device or its identity. Useful for a machine temporarily out of service or under investigation; it can be reactivated.
Revoked: the authorization is permanently withdrawn. The device immediately loses access to the network and should be re-enrolled, with a new identity, if it must come back.
Expired: the authorization has reached its term (invitation or key past its deadline). The device stays off the network until it is re-authorized.

Enrollment security

Enrollment is not just about handing out a secret. Each machine holds a cryptographic identity, and the control plane distributes a signed view of the network, so a device can neither impersonate another nor forge a topology.

Ed25519 identity: at enrollment, the machine generates an Ed25519 key pair. The public key becomes its stable identity in the workspace; the private key never leaves the device.
Signed netmap: the controller distributes to each node a signed network map (netmap) describing the authorized peers and their addresses. A node rejects anything not signed by the controller.
End-to-end encrypted sessions: once enrolled, machines talk over QUIC/TLS 1.3, directly peer to peer.
Time- and use-bounded authorizations: pre-authorized keys and invitations expire, which limits the exposure window of an enrollment secret.