Skip to content

Set Up a Virtual Machine

A Virtual Machine (VM) is the Execution Environment of an Assembly — the machine users and CI jobs connect to in order to reach the Assembly's hardware. This page covers registering a VM, configuring it, storing its credentials, and assigning it to an Assembly.

An Assembly without an assigned VM has no access path and cannot be used for sessions. A VM is one of two kinds:

  • Managed — the machine runs in a Cluster operated by Vector. You only register it in vHaaS; nothing is installed on the machine itself.
  • Self-managed — the machine is your own hardware and additionally needs the vHaaS Agent installed so vHaaS can reach it.

The steps are the same for both; step 3 applies only to self-managed machines.

Create and Assign a Virtual Machine

Prerequisites

You need:

  • A vHaaS account with the Organization Admin role — your role is shown under Profile → User Information
  • A Cluster with at least one Partition — see Manage Clusters
  • The machine's hostname, and its IP address if it has a static one
  • A local administrator account on the machine
  • For self-managed machines: the agent prerequisites

Steps

1. Create the Virtual Machine

Open the Connect Virtual Machine dialog from the menu in the Navbar, or from the Virtual Machines view of a Cluster in the Explorer.
Field Required Description
Hostname Yes Host name of the machine. Also used as the DNS name shown on the Assembly page and searchable in the Explorer.
IP No Static IP address of the machine.
Operating System Yes Windows or Linux. Determines which agent installation commands vHaaS shows for the machine.
Connectivity Mode Yes Cloudflare Tunnel — vHaaS reaches the machine through an outbound tunnel, so no inbound ports have to be opened. Requires outbound UDP/TCP 7844.
Direct Network — vHaaS reaches the machine directly on the network.
Cluster Yes The Cluster the VM is registered under. Must be the same Cluster as the Assembly you assign it to.
Labels No Free-form tags for grouping, e.g. windows, test-vm. Used to target software rollouts and to filter VM inventory.
Key-value properties No Scoped grouping, e.g. project:dummy. Queryable across Clusters.
Agent Control No Enable for self-managed machines. vHaaS then issues a one-time registration token for the vHaaS Agent.

Agent Control cannot be added later

Enable Agent Control while creating the VM. To switch an existing entry over, delete it and create a new one.

2. Store the login credentials

Enter the username and password of the local administrator account on the machine. vHaaS stores them in its secrets management and injects them when a session on the Assembly becomes active — users never see or manage them.
The DNS field is derived from the hostname; the optional IP field here overrides the address used to reach the machine.

Wrong credentials fail at session start, not at creation

The credentials are not verified when you save them. If they are wrong, the VM is created successfully but users cannot log in. Test with a booked session before handing the Assembly over.

3. Install the vHaaS Agent

Self-managed machines only. The "Connect new Virtual Machine" dialog appears with the registration token and the installation commands for the operating system you selected.

One hour to complete

The token is single-use, expires after one hour, and is shown only once. Keep the dialog open. If you lose it, delete the VM entry and create a new one.

Follow vHaaS Agent Setup for the Windows and Linux commands, then reboot the machine.

4. Assign the Virtual Machine to an Assembly

Assign the VM in whichever place fits your workflow:

  • Assembly settings — open the Assembly, go to Settings, scroll down to the Virtual Machine section, and move the VM from Not assigned to Assigned.
  • Explorer — in the Cluster's Virtual Machines view, use the Assign to assembly action on the VM row.
  • During Assembly creation — the assembly upload dialog has an Assign a Virtual Machine step.

An Assembly and its VMs always belong to the same Cluster. An Assembly needs at least one assigned VM to be accessible; if several are assigned, users pick one in the connect dialog.

5. Verify the setup

Book the Assembly and connect to the VM.
Only one user can be connected to a machine at a time. If you are already logged in locally, opening the web session disconnects that session — test from a separate device.

Troubleshooting

Symptom Likely cause Solution
Connect Virtual Machine is missing from the menu Your account is not an Organization Admin Ask an Organization Admin to grant the role from Manage users
The Cluster you need is not in the Cluster dropdown The Cluster has no Partition, or you have no admin rights on it Add a Partition — see Manage Clusters. Clusters under Managed Resources are operated by Vector and cannot be modified.
The Connect Virtual Machine dialog closes unexpectedly Clicked outside the modal Reopen it from the menu
The VM does not appear in the Explorer You are looking at the wrong context VMs are only listed in the Cluster context, not at organization or group level
Assembly stays On-Stock and cannot be booked No Cluster assigned to the Assembly Assign the Assembly to a Cluster and Partition
The Connect dialog shows no VM No VM is assigned to the Assembly Assign the VM — see step 4
The VM is missing from the Not assigned list in the Assembly settings The VM is in a different Cluster, or already assigned to another Assembly Register the VM in the Assembly's Cluster, or release it from the other Assembly
Login to the VM fails after booking Wrong or outdated stored credentials Re-enter them with the Edit credentials action on the VM
The VM shows offline (Agent Control) Agent not running, or the tunnel is blocked Run vhaas-agent doctor on the machine — see Agent troubleshooting
The VM shows online but remote sessions do not open Connectivity Mode is Cloudflare Tunnel and outbound UDP/TCP 7844 is blocked — the control channel on 443 still works Allow the tunnel ports — see Network requirements
Agent registration fails with 401 Token expired, already used, or older than one hour Delete the VM entry, create a new one, and use the fresh token
A device is reachable in vHaaS but not from the VM connection or ip mismatch in the Assembly Profile See Assembly Profile Integration
Deleting a Cluster Partition is rejected The Partition still contains Assemblies with assigned VMs Unassign the VMs and remove the Assemblies first

Manage an Existing Virtual Machine

VMs are listed in the Virtual Machines view of a Cluster in the Explorer. They are not shown at organization or group level. Each row offers these actions:

Action Effect
Edit credentials Replace the stored username and password. Use this after rotating the account password on the machine.
Assign to assembly Attach the VM to an Assembly in the same Cluster, or release it.
Edit Change hostname, IP, labels, and key-value properties.
Delete Remove the VM entry. Unassign it from its Assembly first, otherwise the Assembly loses its access path.

An Assembly's currently assigned VMs are also listed with their DNS name and labels on the Assembly's Setup tab.

To create or update VMs in bulk, use the virtual-machines endpoints of the v3 API or the Python CLI, which can create a VM and pull its technical-user credentials from Vault in one call.

Assembly Profile Integration

The VM provides the host environment; the Assembly Profile describes the hardware and, per device, how that device is wired to the VM. Both have to agree, or the hardware is visible in vHaaS but unusable from the VM.

The profile fields that concern the VM are:

Field Purpose
connection How the device attaches to the VM — usb and eth for direct connections, WuT_gigabit, Silex_DS-600, SEH_Pro and similar for network-attached device servers.
ip Address of the device. Required when connection is WuT_gigabit or WuT_megabit.
vm_uplink Marks a device that has a 10G uplink to the VM.

Practical consequences:

  • A device that vHaaS reports as present but that never shows up on the VM is almost always a wrong connection value or a missing/incorrect ip.
  • Devices behind a USB device server (Silex_DS-600, SEH_Pro, SEH_ProMax) need the corresponding client software on the VM — part of the standard vHaaS software configuration, but worth checking on self-managed machines.
  • Changing how hardware is cabled means updating the profile as well. Profile changes are applied by re-uploading the Assembly Profile, not by editing the VM.

For the full field reference and validation rules, see Assembly Profile.