Skip to content

Install on Linux

Extract the Tarball

Copy the agent tarball to the host and extract it. Run the following command in a terminal on the host (replacing 1.0.0 with the actual version number you downloaded):

$ tar xf cruxvpn-agent-1.0.0.tar.gz

This will extract the agent tarball to a directory called cruxvpn-agent-1.0.0.

Run the Installer

The installer must be run as root. After extracting the tarball, run the following commands in the terminal on the host to run the installer:

$ cd cruxvpn-agent-1.0.0/
$ sudo ./install.sh --install
running as root
install 1.0.0
agent configuration found at /etc/cruxvpn/cruxvpn.conf
agent setup found at /etc/cruxvpn/cruxvpn-setup.conf
/etc/cruxvpn/cruxvpn.conf mode ok (-rw-r-----)
WARNING /etc/cruxvpn/cruxvpn.conf owner should be root
fix owner? ([y]es, [n]o): y
OK will fix owner
fixed owner
...
...
...
WARNING daemon dead
start daemon? ([y]es, [q]uit): y
OK will start daemon
Created symlink /etc/systemd/system/default.target.wants/cruxvpn-agent.service → /etc/systemd/system/cruxvpn-agent.service.
started daemon
install SUCCESS

Next Steps

  1. If you run into errors with the installer, check the Troubleshooting section of this page.
  2. Otherwise, check the host's main page in the app. The Agent panel should show the results of the agent's latest ping.
  3. If the Agent panel simply reads Set Up Agent, or if the Interfaces panel shows the host's interfaces as Down, check the Agent Troubleshooting page.

Logging

In addition to writing output to stdout, the installer also writes similar output to a log file on the host, located here:

/var/log/cruxvpn-install.log

You can refer to this log file to help determine what, where, and when the installer installed something on your host. Our support staff may also ask you to send us this log when we're helping you troubleshoot installation issues.

Other Options

Run the installer with the --help flag to see the other installer options:

$ ./install.sh --help
Crux VPN Agent installer.

Installs the Crux VPN Agent as a daemon in a python virtualenv.

Usage:
  install.sh --help
  install.sh --dryrun [--install | --remove]
  install.sh --install [--force]
  install.sh --remove [--force]
  install.sh --version

Options:
  -h --help     Show this help
  -d --dryrun   Run all installer checks without installing/removing anything
  -f --force    Automatically answer yes to all prompts
  -i --install  Install the agent
  -r --remove   Remove the agent
  -v --version  Show version number

Environment variables:
  INSTALL_CNF       Path to agent config directory ('/etc/cruxvpn')
  INSTALL_LOG       Path to installer log ('/var/log/cruxvpn-install.log')
  INSTALL_PYTHON    Path to python executable ('python3')
  INSTALL_SCRIPTS   Path to extra scripts ('/usr/local/lib/cruxvpn/agent/scripts')
  INSTALL_SRC       Path to agent source code ('/root/cruxvpn-agent-1.0.0')
  INSTALL_VENV      Path to agent virtualenv ('/opt/venvs/cruxvpn-agent')
  USR_LOCAL         Path to /usr/local directory or equivalent

Dryrun

Running the installer with the --dryrun flag will run through the installer steps without actually doing anything to your host. It will output lines beginning with ERROR, WARNING, or OK to indicate what it will or will not do:

  • ERROR to indicate a missing component that will block the installation (like a missing agent configuration file)
  • WARNING to indicate a missing component that the installer will install (like libsodium)
  • OK to indicate what the installer will do to install the missing component

You don't have to run the installer as root for a dry run; however, the output may not be fully accurate unless you do.

$ sudo ./install.sh --dryrun
running as root
dryrun force install 1.0.0
agent configuration found at /etc/cruxvpn/cruxvpn.conf
agent setup found at /etc/cruxvpn/cruxvpn-setup.conf
/etc/cruxvpn/cruxvpn.conf mode ok (-rw-r-----)
WARNING /etc/cruxvpn/cruxvpn.conf owner should be root
OK will fix owner
WARNING /etc/cruxvpn/cruxvpn.conf group should be root
OK will fix group
/etc/cruxvpn/cruxvpn-registration.conf mode ok (-rw-rw----)
WARNING /etc/cruxvpn/cruxvpn-registration.conf owner should be root
OK will fix owner
WARNING /etc/cruxvpn/cruxvpn-registration.conf group should be root
OK will fix group
/etc/cruxvpn/cruxvpn-setup.conf mode ok (-rw-r-----)
WARNING /etc/cruxvpn/cruxvpn-setup.conf owner should be root
OK will fix owner
WARNING /etc/cruxvpn/cruxvpn-setup.conf group should be root
OK will fix group
wireguard found at /usr/bin/wg
iptables found at /usr/sbin/iptables
libsodium found at /lib/aarch64-linux-gnu/libsodium.so.23
WARNING liboqs not found
OK will download liboqs from https://dl.sirius.computer/liboqs/liboqs-ubuntu-24.04-aarch64.so.0.11.0
python 3.12.3 found at /usr/bin/python3
WARNING python missing these packages: ensurepip
OK will install missing packages
WARNING python virtualenv not found at /opt/venvs/cruxvpn-agent
OK will create virtualenv
WARNING agent package not installed
OK will install agent
OK will install scripts
WARNING service definition not found at /etc/systemd/system/[email protected]
OK will define cruxvpn-wg service
WARNING systemd daemon not found at /etc/systemd/system/cruxvpn-agent.service
OK will install daemon
WARNING daemon dead
OK will start daemon
dryrun complete

Force

Running the installer with the --force flag will automatically select yes for all prompts. This is how you'd want to run the installer as part of an automated deploy script.

$ sudo ./install.sh --install --force

Upgrade

To upgrade the agent, download the latest version of the agent tarball, extract it, and run its normal installer script as root:

$ sudo ./install.sh --install
running as root
install 1.0.1
agent configuration found at /etc/cruxvpn/cruxvpn.conf
...
WARNING agent 1.0.0 package outdated (1.0.1 available)
install agent from /root/cruxvpn-agent-1.0.1? ([y]es, [q]uit): y
OK will install agent
...
daemon running
install SUCCESS

This will install the new version of the agent, and then restart the agent daemon. It will not interrupt Crux VPN connections.

Deregister

To deregister a host from the Arqit SKA-Platform™ (SKA-P), make sure the host has a registration file with current credentials. Then run the following command on the host as root:

$ sudo /opt/venvs/cruxvpn-agent/bin/cruxvpn-deregister

Uninstall

To remove the agent, run its installer script as root with the --remove option:

$ sudo ./install.sh --remove
running as root
remove 1.11.1
WARNING daemon running
stop daemon? ([y]es, [q]uit): y
OK will stop daemon
...
WARNING agent credentials found at /etc/cruxvpn/cruxvpn-credentials.conf
delete configuration? ([y]es, [n]no): y
OK will delete credentials
deleted credentials
agent setup not found at /etc/cruxvpn/cruxvpn-setup.conf
remove SUCCESS

This will remove the agent and the Crux VPN tunnels it manages. It will not deregister the host from the SKA-P.

Requirements

The agent requires Python 3.8 or newer, libsodium, and liboqs 0.11.0. The installer can install the first two requirements for you on most Linux platforms via package manager; and either download a pre-compiled version of liboqs, or compile it for you.

Python

If the installer can't install Python for you, try these instructions for building Python on the host manually; or try installing Python via a tool like uv.

Make sure you install at least Python 3.8 or newer. Once you install Python, use the INSTALL_PYTHON environment variable to point the agent installer to your Python executable:

$ sudo INSTALL_PYTHON=/usr/bin/python3.8 ./install.sh --install

Libsodium

If the installer can't install libsodium for you, follow the Libsodium Installation instructions from the libsodium documentation to build and install libsodium on the host manually.

If you installed libsodium into /usr/local/lib, make sure /usr/local/lib is in your shared library path. Run ldconfig -p | grep libsodium to check. If not, add /usr/local/lib to your /etc/ld.so.conf file, and then run the ldconfig command (as root).

Liboqs

If the installer can't install libsodium for you, follow the Platform specific notes for building liboqs documentation to build and install liboqs on the host manually.

If you installed liboqs into /usr/local/lib, make sure /usr/local/lib is in your shared library path. Run ldconfig -p | grep liboqs to check. If not, add /usr/local/lib to your /etc/ld.so.conf file, and then run the ldconfig command (as root).

Troubleshooting

Any WARNING output the installer generates are issues the installer will automatically fix for you (if you answer yes to its prompts). But if you see any ERROR output, here's what to do:

Must run as root

If the installer outputs ERROR must run as root, make sure you are running the installer as the root user. Try running the installer with the sudo command, like sudo ./install.sh --install.

Agent configuration not found

If the installer outputs ERROR agent configuration not found, make sure you've downloaded the cruxvpn.conf file and moved it to /etc/cruxvpn/cruxvpn.conf on the host. See the Set Up Host instructions for details.

Agent credentials not found

If the installer outputs ERROR agent credentials not found, make sure you've downloaded the cruxvpn-setup.conf file and moved it to /etc/cruxvpn/cruxvpn-setup.conf on the host. See the Set Up Host instructions for details.

Unable to install libsodium

If the installer outputs ERROR unable to install libsodium, follow the Libsodium installation instructions to install libsodium manually, and then re-run the installer.

Unable to install liboqs

If the installer outputs ERROR unable to install liboqs, follow the Liboqs installation instructions to install liboqs manually, and then re-run the installer.

Unable to install python

If the installer outputs ERROR unable to install python, follow the Python installation instructions to install Python manually, and then re-run the installer. When you re-run the installer, make sure you set the INSTALL_PYTHON environment variable to the path to the Python executable you just installed (eg sudo INSTALL_PYTHON=/usr/bin/python3.8 ./install.sh --install).

Python 3.8 required

If the installer outputs ERROR python 3.x.x found at /usr/bin/python3 but at least 3.8 required, follow the Python installation instructions to install Python manually, and then re-run the installer. When you re-run the installer, make sure you set the INSTALL_PYTHON environment variable to the path to the Python executable you just installed (eg sudo INSTALL_PYTHON=/usr/bin/python3.8 ./install.sh --install).

Unable to install missing python packages

If the installer outputs ERROR unable to install missing python packages, follow the Python installation instructions to install Python manually, and then re-run the installer. When you re-run the installer, make sure you set the INSTALL_PYTHON environment variable to the path to the Python executable you just installed (eg sudo INSTALL_PYTHON=/usr/bin/python3.8 ./install.sh --install).

Failed building wheel for pynacl

If the installer outputs ERROR: Failed building wheel for pynacl, or displays similar errors like:

  • pip subprocess to install build dependencies did not run successfully
  • Installing build dependencies ... error
  • Encountered error while trying to install package cffi
  • command 'gcc' failed: No such file or directory
  • The 'make' utility is missing from PATH
  • ffi.h: No such file or directory

Install your OS's gcc, make, libffi-dev (or libffi-devel), and python3-dev (or python3-devel) packages, and then re-run the installer.

The following commands will make sure you have the necessary OS packages to build the PyNaCl wheel on most Linux distributions:

  • On Debian-based distros, run sudo apt-get install gcc libffi-dev make python3-dev.
  • On Fedora-based distros, run sudo dnf install findutils gcc libffi-devel make python3-devel.
  • On Arch-based distros, run sudo pacman -Sy gcc make libffi.
  • On Alpine-based distros, run doas apk add gcc libffi-dev make musl-dev python3-dev.