Install VIGIL Mesh on Linux (desktop, server and Jetson)

Prerequisites

The Linux client serves three uses: the desktop, the headless server (or site machine), and the embedded board such as a Jetson. Installation creates a TUN interface and a systemd-managed service, and needs root rights for the duration of the install and sign-in.

• A Debian- or Ubuntu-based distribution with glibc 2.34 or newer — Ubuntu 22.04 LTS, Debian 12 or newer — on amd64 or arm64 (for example JetPack 6 / Ubuntu 22.04 on an NVIDIA Jetson board; JetPack 5 / Ubuntu 20.04 is too old).
• Root rights (sudo) to install the package, create the TUN interface and enable the service.
• An active systemd and TUN interface support (/dev/net/tun), standard on common distributions.
• The ca-certificates, iproute2, nftables and systemd packages — client dependencies, resolved automatically by apt.
• Outbound Internet access: no inbound firewall rule or port forwarding to set up.

Recommended method: the install script

The official install-vigil-mesh.sh script detects the architecture, reads the published manifest, picks the right package, verifies its SHA-256 checksum, installs it, then enables and starts the service. In an interactive terminal, it then starts the wizard: choice between enrollment key and account, authentication, catalog refresh and persistent network selection.

curl -fLO https://vigil.design/downloads/install-vigil-mesh.sh
chmod +x ./install-vigil-mesh.sh
sudo ./install-vigil-mesh.sh

• Choice 1 — enrollment key: in the console, open the network, then “Add a machine” and expand “Use an enrollment key”. The key starts with vek_, expires after one hour and works once. Paste it at the prompt: input is hidden and the key never travels through process arguments.
• Choice 2 — account: the wizard asks for the email address and password; if the account is protected, it also asks for the MFA code.
• If the machine is already connected, its session is closed only once the new credentials have been entered: an abandoned prompt leaves a remote machine online.
• A network number toggles that network without losing the other choices; all selects everything and none clears the selection.
• Enter q or Q to apply the displayed selection and exit the wizard cleanly.
• Without an interactive terminal, or with --skip-onboarding, the script only installs the package and service: it asks for no secret and changes no attachment.
• After the machine reboots there is nothing to redo: the systemd service starts on its own, renews the session and restores the selected networks.

Headless machine or bulk install: pass the enrollment key on standard input with --enroll-key-stdin. The script then asks nothing. With --workspace and --network it attaches that exact network — this is the command the console displays, ready to copy; without them it attaches the network only when exactly one is available.

curl -fLO https://vigil.design/downloads/install-vigil-mesh.sh
chmod +x ./install-vigil-mesh.sh
printf '%s\n' 'vek_…' | sudo ./install-vigil-mesh.sh --enroll-key-stdin --workspace <workspace-id> --network <network-id>

Manual method: the .deb package

If you prefer full control, install the package by hand. Get the .deb for your architecture from /download/client — amd64 for an x86-64 desktop or server, arm64 for an ARM 64-bit board (Jetson included) — along with the SHA-256 checksum published in the signed manifest.

# 1. Verify the SHA-256 checksum against the signed manifest
sha256sum vigil-mesh_<version>_amd64.deb

# 2. Install the package (apt resolves dependencies)
sudo apt install ./vigil-mesh_<version>_amd64.deb

# 3. Enable and start the service at boot
sudo systemctl enable --now vigil-mesh.service
sudo systemctl status vigil-mesh.service

Manual sign-in after a non-interactive installation

These commands are only needed after a manual .deb install, a run without an interactive terminal, or the --skip-onboarding option. Authenticate the machine through standard input — with the account or with an enrollment key — then inspect the catalog and explicitly attach every network you need. Multiple networks can stay attached at the same time: repeat the attach command without replacing existing attachments.

• Secret outside arguments: the password is passed only through stdin with --password-stdin, the enrollment key with --key-stdin.
• Explicit catalog: vigil-mesh account refresh displays the workspace/network pairs available to the account; vigil-mesh network list displays the networks already attached and their state.
• Multiple attachments: vigil-mesh network attach adds one network; run it again for every additional network you need.

# Read the password without echoing it or placing it in argv
read -rsp 'VIGIL password: ' VIGIL_PASSWORD; echo
printf '%s\n' "$VIGIL_PASSWORD" | sudo vigil-mesh account login --login you@example.com --password-stdin
unset VIGIL_PASSWORD

# … or redeem an enrollment key from the console
printf '%s\n' 'vek_…' | sudo vigil-mesh account enroll --key-stdin

sudo vigil-mesh account status

# List the available networks, then attach the ones you need
sudo vigil-mesh account refresh
sudo vigil-mesh network attach --workspace <workspace-id> --network <network-id>
# Repeat attach for every additional network you need.

MFA: the second factor at sign-in

The interactive wizard detects the mfa-required state and asks for the TOTP code directly. For a manual sign-in, pass that code through stdin with the account mfa command and the challenge token returned by sign-in. The code never appears in the process arguments.

• The password goes through --password-stdin; no option carries the secret in argv.
• The MFA code goes separately through --code-stdin, with the challenge token returned by sign-in.
• After the ready state, use account refresh and then network attach for all required networks.

read -rsp 'MFA code: ' VIGIL_MFA; echo
printf '%s\n' "$VIGIL_MFA" | sudo vigil-mesh account mfa --token <challenge-token> --code-stdin
unset VIGIL_MFA
sudo vigil-mesh account status

Manage the service

The client runs as the vigil-mesh.service systemd unit, enabled at boot. After the machine restarts, it renews the session and restores the configured attachments, with nothing to type again.

# Service state and client health
systemctl status vigil-mesh.service
vigil-mesh --self-test
sudo vigil-mesh account status
sudo vigil-mesh network list

# Logs
journalctl -u vigil-mesh.service -n 80 --no-pager

# Stop or restart
sudo systemctl stop vigil-mesh.service
sudo systemctl restart vigil-mesh.service

# Sign out (removes the local session)
sudo vigil-mesh account logout

Verify

After confirming the wizard with q, or after manual sign-in and attachments, check the service, session and each network state. These checks distinguish a healthy installation from an attachment that is actually connected.

• Healthy service: systemctl status vigil-mesh.service and vigil-mesh --self-test succeed.
• Ready account: sudo vigil-mesh account status reports the ready state.
• Attached networks: sudo vigil-mesh network list shows every required attachment and its state, without limiting the machine to one network.
• Name resolution: MagicDNS resolves other devices' names locally, with no query leaving the machine.
• Reachability: a simple test (ping the mesh address of another node, then reach a shared service) confirms the path is open.