Skip to content

vHaaS Agent Setup

This guide walks you through connecting a machine to vHaaS so that it can be shared across your organization and used to access connected hardware remotely.

You will:

  1. Create the organizational structure in vHaaS (cluster, partition).
  2. Register the machine as a virtual machine entry in vHaaS and get a registration token.
  3. Install and configure the vHaaS agent on the machine.
  4. Link the machine to an assembly and verify the connection.

Install the vHaaS Agent

Prerequisites

  • A vHaaS account with the Organization Admin role. To check, open Profile in the navigation bar — your role is listed under User Information. If you do not have the role, ask an Organization Admin in your organization to grant it; they can do this from Manage users.
  • A machine (physical or virtual) with internet access and DNS resolution
  • Admin access to your machine
  • The apt package manager (Linux) or PowerShell (Windows)
  • Outbound network access on TCP 443, UDP/TCP 7844, DNS 53, NTP 123

Network access (firewall)

All ports are outbound only. For the CloudflareD tunnel (UDP/TCP 7844), see Cloudflare's Tunnel with firewall guide for the full list of IP ranges to allow.

Windows antivirus/anti-malware

The installer also installs CloudflareD as a Windows service. Some anti-malware solutions block it — add an exception before starting.

Raspberry Pi or devices without a hardware TPM

If your device has no built-in security chip (TPM 2.0), you need an additional software TPM package, marked in Step 4.

Steps

A Cluster is the rack unit that provides network, power, and server connectivity for one or more Assemblies. A Cluster Partition subdivides a Cluster for a single organization and defines how many Assembly slots it has. Both terms are defined in the Glossary; see also Cluster.

You can skip steps 1 and 2 if you already have a Cluster and Partition.

1. Create a Cluster

See Create a Cluster.

2. Create a Partition

See Create a Cluster Partition.

3. Register the machine in vHaaS

Create a Virtual Machine with Agent Control enabled — it is required for the agent — and the machine's administrator credentials.

The "Connect new Virtual Machine" dialog with installation commands appears. Keep this browser tab open — the steps below refer to it.

Registration window

You have one hour to complete the agent installation. The token is single-use and shown only once. If you lose the dialog, delete the VM entry and create a new one.

4. Install the vHaaS agent

Open a PowerShell session with Administrator privileges on the target machine.

Add the Vector package registry:

choco source add --name="vector" --source="https://packages.vehub.vector.com/nuget/index.json"

Install the agent:

choco install vector-vehaas-agent -y

The vehaas in the package ID is intentional

The command itself is vhaas-agent, but the Chocolatey package keeps its original ID so existing installations retain an upgrade path. On Linux the package is vector-vhaas-agent.

If the installation fails you need to install the cloudflareD package separately

Ensure that choco community packages are enabled 

choco source enable -n=chocolatey
Install the cloudflareD package 
choco install cloudflared -y

Run the setup command from the dialog in step 3 — it already contains your registration token and the URLs of your vHaaS instance:

vhaas-agent.exe setup --registration-token <your-token> --config-vhaas-proxy-url https://<vhaas-host> --config-rabbitmq-url wss://<vhaas-host>/mqtt

The installer adds the agent to the system PATH, so the command needs no .\ path qualifier and no cd into the install directory. If PowerShell reports that the command is not found, open a new PowerShell session so it picks up the updated PATH.

Open a terminal with sudo access on the target machine.

Add the package sources:

sudo mkdir -p --mode=0755 /usr/share/keyrings
wget -qO - https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main" >> /etc/apt/sources.list.d/cloudflared.list'
wget -O - https://packages.vehub.vector.com/apt/vector-pkg.key | sudo gpg --dearmor -o /usr/share/keyrings/vector-pkg.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/vector-pkg.gpg] https://packages.vehub.vector.com/apt generic main" >> /etc/apt/sources.list.d/vector.list'
sudo apt-get update

Install the agent:

sudo apt-get install -y vector-vhaas-agent

Raspberry Pi or device without a TPM chip

Also install the software TPM helper: 

sudo apt-get install -y linux-headers-$(uname -r) vhaas-agent-swtpm

Run the setup command from the dialog in step 3 — it already contains your registration token and the URLs of your vHaaS instance:

sudo vhaas-agent setup --registration-token <your-token> --config-vhaas-proxy-url https://<vhaas-host> --config-rabbitmq-url wss://<vhaas-host>/mqtt

Verify the service is running:

systemctl is-active vhaas
  1. In vHaaS, navigate to your Assembly.
  2. Navigate to Settings in the left sidebar.
  3. Scroll to the Virtual Machine section.
  4. Move your VM from the Not assigned to the Assigned list.

For the alternative places to assign a VM, see Set Up a Virtual Machine.

6. Reboot the machine

Restart the machine so all services initialize cleanly. vhaas-agent setup offers to reboot for you when it finishes; if you declined, or ran it with --non-interactive, restart now.

7. Reserve the Assembly and connect

  1. Book an assembly in vHaaS
  2. Connect and work on your VM

Single-user sessions

Only one user can be connected to a machine at a time. If you are already logged in, opening the web session will disconnect the current session. Use a separate device to test the connection.

Cleanup and re-installation

If a previous attempt needs to be removed before retrying:

CloudfareD is a dependency for the vHaaS agent and needs to be uninstalled manually.

  1. Uninstall the vHaaS agent and CloudflareD: 

    choco uninstall vector-vehaas-agent cloudflared -y
    If this fails, manually delete C:\Program Files\vhaas-agent.

  2. Delete the agent data directory C:\ProgramData\vhaas-agent (hidden folder).

  3. Restart the machine.

  4. In vHaaS, delete the old VM entry and create a new one.

sudo apt-get purge -y vector-vhaas-agent vhaas-agent-swtpm cloudflared

Then delete the VM entry in vHaaS and create a new one.

Exit codes for automated agent installations

If you script the installation — for example with Ansible — run the setup command with --non-interactive and branch on the agent's exit code instead of parsing its output. Every failure class has a distinct, stable exit code; the complete table and an Ansible example are in the vHaaS Agent reference. Error messages are written to standard error.

Troubleshooting

Symptom OS Likely cause Resolution
Agent reports no such host Windows DNS not configured on the machine Configure a DNS server for the network adapter.
Network drops after installation Windows CloudflareD conflicting with antivirus Add a CloudflareD antivirus exception; check for IP conflicts.
CloudflareD service missing from Windows Services Windows Cloudflare repository not set up before install Uninstall and reinstall the agent.
vhaas-agent.exe not found Windows The PowerShell session predates the install, so its PATH is stale Open a new PowerShell session.
systemctl is-active vhaas shows inactive Linux Service failed to start Check journalctl -u vhaas -n 50 for errors; reboot and retry.
Registration fails with 401 Both Token invalid, expired, or already used Obtain a new token — see Troubleshooting.
Registration fails with 409 Both VM already has keys registered An administrator must clear the keys first — see Re-registering a machine.
Remote session won't open, but the VM shows online Both CloudflareD tunnel blocked (outbound 7844) Allow the tunnel ports — see Network access (firewall).
Connect Virtual Machine dialog closes unexpectedly Both Clicked outside the modal Reopen via the icon.
Any other agent error Both See the agent reference Start with vhaas-agent doctor — see Troubleshooting.