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, on amd64 (Ubuntu 24.04 LTS or newer) or arm64 (for example JetPack 6 / Ubuntu 22.04 on an NVIDIA Jetson board).
• 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, iptables 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. It signs in to no account and attaches no network: those actions remain explicit after installation.

# 1. Download the official install script
curl -fLO https://vigil.design/downloads/install-vigil-mesh.sh

# 2. (Recommended) read it before running it
less install-vigil-mesh.sh

# 3. Run it: amd64/arm64 detection, SHA-256 verification,
#    install and service activation, with zero attachments.
chmod +x ./install-vigil-mesh.sh
./install-vigil-mesh.sh

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

Account sign-in and network attachments

Installation intentionally leaves zero attachments. Sign in to the account through standard input, 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.
• Explicit catalog: vigil-mesh network list displays the workspace/network pairs available to the account.
• 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
sudo vigil-mesh account status

# List and attach the networks you need
sudo vigil-mesh network list
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

If sign-in returns the mfa-required state and a challenge token, pass the TOTP code through stdin with the account mfa command. 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 network list 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. It restores configured attachments after the machine restarts.

# Service state and client health
systemctl status vigil-mesh.service
vigil-node --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 account sign-in and explicit 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-node --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.