Set Up an Execution Environment

An Execution Environment is the machine users and CI jobs connect to in order to reach the hardware of an Assembly — a physical machine such as a PC, NUC or Raspberry Pi, or a virtual machine. This page covers registering an Execution Environment, configuring it, storing its credentials, and assigning it to an Assembly.

An Assembly without an assigned Execution Environment has no access path and cannot be used for Sessions. An Execution Environment is one of two kinds:

Managed — the machine runs in a Cluster operated by Vector. Vector installs and operates the vHaaS Agent on it; you do not install anything on the machine yourself.
Self-managed — the machine is your own hardware. You install the vHaaS Agent on it yourself so vHaaS can reach it.

The steps are the same for both kinds; you do step 3 only on self-managed machines.

Create and Assign an Execution Environment

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 Execution Environment

Open the Connect Execution Environment dialog from the menu in the Navbar, or from the Execution Environments 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 Execution Environment 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 the Execution Environment 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 Execution Environment. To switch an existing entry over, delete it and create a new one.

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 Execution Environment 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; on managed machines Vector installs the agent. The "Connect new Execution Environment" 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 Execution Environment entry and create a new one.

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

4. Assign the Execution Environment to an Assembly

Assign the Execution Environment in whichever place fits your workflow:

Assembly settings — open the Assembly, go to Settings, scroll down to the Execution Environments section, and move the Execution Environment from Not assigned to Assigned.
Explorer — in the Cluster's Execution Environments view, use the Assign to assembly action on the Execution Environment row.
During Assembly creation — the Add Assembly dialog has an Assign Execution Environment step.

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

5. Verify the setup

Book an Assembly and Work on an Execution Environment.

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 Execution Environment is missing from the menu	Your account is not an Organization Admin	Ask an Organization Admin to grant the role
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 Execution Environment dialog closes unexpectedly	Clicked outside the modal	Reopen it from the menu
The Execution Environment does not appear in the Explorer	You are looking at the wrong context	Execution Environments 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 Execution Environment	No Execution Environment is assigned to the Assembly	Assign the Execution Environment — see step 4
The Execution Environment is missing from the Not assigned list in the Assembly settings	The Execution Environment is in a different Cluster, or already assigned to another Assembly	Register the Execution Environment in the Assembly's Cluster, or release it from the other Assembly
Login to the Execution Environment fails after booking	Wrong or outdated stored credentials	Re-enter them with the Edit credentials action on the Execution Environment
The Execution Environment shows offline (Agent Control)	Agent not running, or the tunnel is blocked	Run `vhaas-agent doctor` on the machine — see Agent troubleshooting
The Execution Environment 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 Execution Environment entry, create a new one, and use the fresh token
A device is reachable in vHaaS but not from the Execution Environment	`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 Execution Environments	Unassign the Execution Environments and remove the Assemblies first

Manage an Existing Execution Environment

Execution Environments are listed in the Execution Environments 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 Execution Environment to an Assembly in the same Cluster, or release it.
Edit	Change hostname, IP, labels, and key-value properties.
Delete	Remove the Execution Environment entry. Unassign it from its Assembly first, otherwise the Assembly loses its access path.

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

To create or update Execution Environments in bulk, use the Execution Environment endpoints (virtual-machines) of the v3 API.

Assembly Profile Integration

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

The profile fields that concern the Execution Environment are:

Field	Purpose
`connection`	How the device attaches to the Execution Environment — `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 Execution Environment.

Practical consequences:

A device that vHaaS reports as present but that never shows up on the Execution Environment 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 Execution Environment — 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 Execution Environment.

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

Execution Environment — what an Execution Environment is, connection methods, software environment
Assembly — the reservable hardware unit an Execution Environment is assigned to
Assembly Profile — the JSON model that describes device-to-Execution-Environment wiring
Work on an Execution Environment — connect to the Execution Environment and use it once the Assembly is booked
vHaaS Agent Setup — full agent installation guide for self-managed machines
Manage Clusters — create the Cluster and Partition an Execution Environment needs