Installation

Install the Nefia CLI and nefia-agent on macOS, Linux, and Windows.

Nefia consists of two binaries:

nefia — The operator CLI that runs on your local machine.
nefia-agent — The agent that runs on target PCs you want to manage.

System Requirements

Platform	Version	Notes
macOS	15+ (Sequoia)	Apple Silicon and Intel supported
Linux	Ubuntu 22.04+	Debian 12+, Fedora 38+. systemd required
Windows	11+	x86_64 and ARM64 supported

Install the Operator CLI

Manual Installation

If you prefer not to use a package manager, you can download the binary directly from the install script or GitHub Releases.

Run the install script:

bash

curl -fsSL https://www.nefia.ai/install.sh | sh

This downloads the latest release, verifies its SHA-256 checksum, and installs the binary to ~/.nefia/bin/nefia. Set the NEFIA_INSTALL_DIR environment variable to customize the install location.

Verify Installation

After installing, verify that the CLI is working:

bash

nefia version

You should see output like:

Terminal

nefia 1.0.0 commit: abc1234 built: 2026-03-05T12:00:00Z go: go1.25.0 os/arch: darwin/arm64

Initial Setup

After installing the CLI, run nefia setup to perform first-time initialization:

bash

nefia setup

setup is the canonical command. nefia init remains available as an alias.

The setup flow runs four phases:

Configuration — Creates nefia.yaml if it does not already exist.
VPN keys — Generates the operator WireGuard keypair if missing.
First host — Optionally collect the first target PC's name and OS.
Invite token — Generates an enrollment token for that host. If login is required and the terminal is interactive, Nefia can open the browser automatically.

Tip

For CI pipelines and scripts, use --non-interactive. Pass --host-name and --host-os when you want setup to generate the first invite token, or --skip-host when you only want config and VPN keys:

bash

nefia setup --non-interactive --host-name my-server --host-os linux
nefia setup --skip-host

Interactive prompts are skipped automatically in non-TTY environments.

Install the Agent

The agent is installed on the target PCs you want to manage. The install script downloads the binary, enrolls the agent, and registers it as a system service — all in one command.

Generate an invite token on the operator PC:

bash

nefia vpn invite --name my-server --os linux --stun

Run the agent installer with the token on the target PC:

bash

curl -fsSL https://www.nefia.ai/install-agent.sh | sh -s -- --token '<INVITE_TOKEN>'

Downloads, verifies the SHA-256 checksum, installs to /usr/local/bin/nefia-agent, enrolls the agent, and registers a system service (launchd on macOS, systemd on Linux).

You can also pass a token file instead: --token-file /path/to/token.txt.

Info

For manual installation without the script, download the binary from the releases page and run:

bash

nefia-agent enroll --token '<INVITE_TOKEN>' --install --yes

The --install flag registers the system service automatically after enrollment.

macOS: Blocked by Gatekeeper

On macOS, Gatekeeper immediately terminates binaries that have not been notarized. The terminal displays the following:

Terminal

sh: line 178: 7416 Killed: 9 "/usr/local/bin/nefia-agent" enroll --token-file ... error: Enrollment failed

Killed: 9 (SIGKILL) means Gatekeeper refused to execute the binary. This can occur with pre-release versions or manually downloaded binaries.

Resolution:

bash

# Remove the quarantine attribute
sudo xattr -d com.apple.quarantine /usr/local/bin/nefia-agent
sudo xattr -cr /usr/local/bin/nefia-agent
 
# Re-run enrollment manually
nefia-agent enroll --token '<INVITE_TOKEN>' --install --yes

If the above does not resolve the issue, open System Settings > Privacy & Security, find the message "nefia-agent was blocked", and click Allow Anyway, then re-run the command.

Windows: Blocked by SmartScreen

On Windows, SmartScreen may block unsigned or unrecognized binaries. PowerShell displays the following:

Terminal

nefia-agent.exe : Operation did not complete successfully because the file contains a virus or potentially unwanted software.

Alternatively, a dialog saying "Windows protected your PC" may appear when running the binary.

Resolution:

Allow from the dialog: Click "More info", then select "Run anyway"
Allow from PowerShell:

powershell

# Remove the Zone.Identifier (download origin information)
Unblock-File -Path "$env:ProgramData\nefia\nefia-agent.exe"
 
# Re-run enrollment manually
nefia-agent.exe enroll --token-file C:\path\to\token.txt --install --yes

Allow from Windows Security: Go to "Windows Security > Virus & threat protection > Protection history", find the relevant block, and select "Allow on device"

Keeping Up to Date

If you installed with a package manager, update using the standard update commands:

bash

# Homebrew
brew upgrade nefia
 
# Scoop
scoop update nefia

For the agent, enable automatic updates by specifying an update interval:

bash

nefia-agent run --auto-update-interval 24h

Next Steps

Quick Start

Set up your first VPN connection and run a remote command.