Skip to content

Run the Agent

The Crux VPN agent is a lightweight service that runs on each installed host to monitor and manage Crux VPN connections. Once set up, no user interaction is needed to use the connections it provides.

Install

To run the agent on a host, do the following:

  1. Add a host entry in the Crux VPN web UI for the host.
  2. Download the setup files to the host.
  3. Supply your Arqit SKA-Platform™ (SKA-P) registration credentials.
  4. Download the agent to the host and run the installer.
  5. Go back to the web UI, and check the status of the host.

If you have already installed the agent, but it does not appear to be working, see the Agent Troubleshooting documentation to troubleshoot it.

Registration

In order for the agent to automatically enroll its host into SKA-P, you need to supply it with the credentials of an SKA-P console user who is authorized to enroll devices. Save these SKA-P credentials in a file called cruxvpn-registration.conf, and place this file in the agent's configuration directory alongside the other agent configuration files:

# /etc/cruxvpn/cruxvpn-registration.conf
[PQC.Registration]
Realm = examplecompany
Username = [email protected]
Password = password123

You may obfuscate the password field with Base64 encoding; for example to obscure a password of password123 by encoding it as cGFzc3dvcmQxMjM=:

PasswordBase64 = cGFzc3dvcmQxMjM=

You may also enroll a device into a specific OU (Organizational Unit) by specifying the UID (Unique Identifier) of the OU:

OU = Ygtpvn-sY_E9t7OVQTPKhW0hO38bhDFLxYOTZEWxHMI=

You may also use "QKey" registration by adding the following settings to the registration configuration (using the QKeyId and QKey values given to you by Arqit):

Mode = QKEY
QKeyId = key123
QKey = mCR7WB-YmLLpV4DBilRXmQbZ0TdmviOt9Lp0SLyQp0A=

Configuration

Most of the other agent settings can be configured in the web UI. However, there are several settings you can add to the [PQC] section of the agent configuration file, like the following example (showing the defaults for these settings):

# cruxvpn.conf generated 1/2/2025, 3:04:05 PM PDT
[Cruxvpn]
# My Server Agent
Agent = 5L3bTsoyaaa
# My Server
Host = 4AzLo5xDaQJ

[PQC]
Rotate = 300
SocketTimeout = 3
Region = uks1
Domain = uks1.quantum.cloud

These are the settings:

  • Rotate: Secret key rotation interval in seconds.
  • SocketTimeout: Peering timeout in seconds.
  • Region: SKA-P API region.
  • Domain: SKA-P API domain (overrides Region).

Also see the DNS page for DNS-related settings you may want to configure (in the [Cruxvpn] section of the agent configuration file).