Skip to content
Portal

VDI (Virtual Desktop Infrastructure)

VDI provides access to Windows desktop environments running as virtual machines. Users connect to VMs via RDP (Remote Desktop Protocol).

Pre-release feature

VDI is behind a pre-release feature flag. The VDI nav item only appears in the portal when the feature has been enabled for your customer. If you don't see it, ask your operator to enable it.

Objectives

  • Create VDI profiles
  • Configure service accounts
  • Manage user roles
  • Request and use VDI sessions

Before you begin

Set these up before creating a VDI profile:

  • A cloudspace with available resources, where the session VMs will run.
  • A VM template or image.
  • A service account role granted access to that cloudspace, and a service account using it (see Roles and Service Accounts).
  • A user role for end users (typically read-only) — this one is granted to the VDI profile itself, which you can do as part of profile creation.

VDI Profiles

A VDI Profile defines the configuration for virtual desktops. Each profile specifies VM resources, behavior, and access control.

The VDI Profiles list shows these columns: Name, Cloudspace, Standby pool size, Maximum number of VMs, Instance behavior, Recycle time (minutes), Sessions count, Backup policy, Status and Actions.

Profile Settings

Instance Behavior

  • single-use: Each session gets a fresh VM, recycled after disconnect and recycle time has passed
  • dedicated: User receives the same VM for each session

Availability — only shown in the wizard for dedicated profiles:

  • stand_by: VM stays running when idle, no recycle time
  • shutdown: VM shuts down once idle past the recycle time

single-use profiles have no availability control in the UI — every single-use VM is always recycled after use, so the concept doesn't apply from the user's perspective.

VM Configuration

  • vCPUs
  • Memory (MiB)
  • Boot disk size (GiB)
  • Base image/template
  • Optional vGPU profile (with a configurable number of vGPU instances per VM)

Pool Settings

  • Standby pool size: Number of VMs kept ready
  • Maximum number of VMs: Maximum concurrent sessions (0 = unlimited)
  • Recycle time (minutes): shown for single-use profiles always, and for dedicated profiles only when availability is shutdown

Creating a VDI Profile

Open VDI in the Admin group of the sidebar (the page has a single VDI Profiles tab) and click Add VDI Profile. The create wizard has six steps:

  1. Choose cloudspace where VMs will be created.
  2. Select image — the base image or template for session VMs. Picking an image row advances to the next step automatically. The list shows only Windows images.
  3. VM configuration: Compute size (vCPUs default 1, Memory in MiB default 4096, Boot disk size in GiB, taken from the image, default 30), Attach vGPU profile (lists the available vGPU profiles) and Assign backup policy, all optional except the compute size.
  4. VM instance behavior: select single-use or dedicated.
    • single-use always shows a Recycle time (minutes) field (default 30).
    • dedicated shows an availability dropdown (stand_by or shutdown) instead; choosing shutdown also reveals the same Recycle time (minutes) field. stand_by shows no recycle time at all.
  5. Connection mode (see Connection Modes): the Agent Connection Mode select (default agent) and the required Interface Address, with a SUGGEST IP NETWORK button.
  6. VDI profile configuration: Name, standby pool size (default 0), Maximum number of VMs (default 0; 0 for unlimited), Service account and User roles (all required), where the user role is the one that can request sessions (the portal recommends a read-only role, and links you to create one if you don't already have a suitable one), and — only for single-use profiles — a Rollback checkbox: new sessions reuse the same VM instead of a fresh one, but the VM is reset to a clean state after each session (uses additional storage for snapshots).
  7. Click ADD (or CANCEL).

The system provisions the standby pool VMs automatically.

Authorization Required

If your account does not yet have the IAM owner scope, the portal first shows an Authorization Required dialog ("The user:ownerof:organization scope for organization ... is needed to continue the operation!") with AUTHORIZE and CLOSE buttons. Click AUTHORIZE to continue; clicking CLOSE cancels the action.

Note

There's no "contact email" field on the profile — that's not part of the real create wizard.

Editing a VDI Profile

To edit a VDI profile

  1. Open VDI in the Admin group of the sidebar.
  2. Select the profile to edit.
  3. Modify the desired settings.
  4. Click Update.

Note: Changes to VM configuration only affect newly created VMs, not existing ones. This will purge the standby pool and create a new pool with the new VM configurations.

Deleting a VDI Profile

To delete a VDI profile

  1. Open VDI in the Admin group of the sidebar.
  2. Select the profile to delete.
  3. Click DELETE at the top of the page. The dialog shows a live count of connected and reserved sessions on the profile.
  4. If there are active sessions, check Force delete to delete them along with the profile.
  5. Click DELETE.

Validating a VDI Image

Next to Add VDI Profile, the VDI page has a Validate VDI Image button. It opens a separate five-step wizard: Select Cloudspace, Select Virtual machine, Select Rollback Snapshot, Connection Mode and Configuration. See Creating a Golden Image for how it fits in the image preparation workflow.

Profile Details Page Tabs

A VDI profile's details page has four tabs:

Tab Contents
Sessions Every session on the profile — see VDI Sessions below.
Workflows Background operations (provisioning, scaling, golden-image publishing, etc.), each with live status. See Workflows below.
Roles and Permissions The user role(s) granted access to this profile — see Granting the User Role to the VDI Profile.
WireGuard The profile's own WireGuard interface, used for Agent-mode sessions — see WireGuard Interface below.

Workflows

Every background operation on the profile — provisioning the standby pool, scaling it up or down, publishing a golden image, and so on — runs as a trackable workflow:

  • The Workflows tab lists them with Title, Created On, Status (Running / Queued / Succeeded / Failed), and Duration. Filter by status using the chips above the list. Updates live as workflows progress.
  • Click a workflow to see its Workflow Diagram — a visual breakdown of its steps.
  • Click a step in the diagram to jump to that step's logs, useful for diagnosing exactly where a failed provisioning or publishing operation went wrong.

WireGuard Interface

The WireGuard tab shows the profile's own WireGuard interface (used for Agent-mode session tunnels) — Name, Address, Port, MTU, Public key, and a Configuration action that shows the peer configuration text you'd need to add this interface as a peer on another device, with a link to the WireGuard tutorial. This is the profile's own infrastructure, separate from the per-session WireGuard peer details shown on each session's own page (see below).

Connection Modes

VDI supports two connection modes for accessing virtual desktops.

Agent Mode

Agent mode uses WireGuard VPN to create direct encrypted connections.

Configuration:

  • Set connection_mode to agent
  • Set an Interface Address for the WireGuard tunnel (e.g. 172.16.3.2/24) — click Suggest IP Network to have the portal pick one that doesn't conflict with your other networks.

User requirements:

  • Install VDI Agent (Windows/macOS/Linux)
  • Internet connection

How it works:

  1. User requests session
  2. VDI Agent establishes WireGuard VPN tunnel
  3. RDP connection routed through VPN
  4. Direct connection to VM

RD Gateway Mode

RD Gateway mode routes connections through an RD Gateway server as a proxy — either the Microsoft Windows RD Gateway role, or the portal's own Linux RD Gateway binary. See RD Gateway and Linux VDI RD Gateway for setup.

Configuration:

  • Set connection_mode to rdgateway
  • Enter the RD Gateway Hostname
  • Set the RDP file lifetime (in minutes) — how long a downloaded .rdp file stays valid. Keep this shorter than the profile's recycle time.
  • From the profile details page, Generate RD Gateway keys to sign .rdp files for the Linux gateway (not needed for the Microsoft RD Gateway role).

Requirements:

  • RD Gateway server deployed
  • Valid SSL certificate
  • RD Gateway hostname configured

How it works:

  1. User requests session
  2. RDP connection to RD Gateway hostname
  3. Gateway proxies connection to VM
  4. No agent or VPN required

Editing the RDP / Remmina File Configuration

On a profile in RD Gateway mode, the Update RDP file config and Update Remmina file config buttons let you edit the raw .rdp / .remmina options that are written into the connection file. Each editor offers a Reset to default option to restore the standard configuration.

Roles

A VDI profile needs two separate roles, each granted access at a different level. Both use the platform's custom-roles mechanism (see Roles & Permissions) — create each role once, then grant it access to the right resource.

  • User role: a narrow, normally read-only role granted to the VDI profile itself. This is what lets end users view the profile's landing page and request sessions. It does not need — and should not have — access to the cloudspace.
  • Service account role: a broader role, granted to the cloudspace where the profile's VMs are created. The service account uses this access to provision and manage the session VMs on users' behalf. Without this cloudspace grant, the service account cannot create or manage VMs there, and VDI provisioning will fail.

Creating the User Role

  1. Open Roles in the Admin group of the sidebar.
  2. Click ADD ROLE.
  3. Enter a Name and Description.
  4. Select Read permission (Create/Update/Execute/Delete are also available, but VDI users only need read access to request sessions).
  5. Click ADD ROLE.

The add-role form has no field for adding users; the role is attached to users through role grants and to service accounts.

Granting the User Role to the VDI Profile

Unlike the service account role below, this grant lives on the VDI profile itself, not on the cloudspace:

  1. Open the VDI profile's details page.
  2. Select the Roles and Permissions tab.
  3. Grant the role you created above.

You can also select this role directly from the Configuration step when creating the profile.

Creating the Service Account Role

  1. Open Roles in the Admin group of the sidebar.
  2. Click ADD ROLE.
  3. Enter a Name and Description.
  4. Select the permissions the service account needs to manage VDI VMs in the cloudspace — full access (Read, Create, Update, Execute, Delete) is typical.
  5. Click ADD ROLE.

Granting the Service Account Role to the Cloudspace

This is the grant that actually lets VDI provisioning work — it must be done before creating the VDI profile:

  1. Navigate to the cloudspace where the profile's VMs will be created.
  2. Click More → Roles & permissions.
  3. Click GRANT ROLE ACCESS.
  4. Select the service account role you created above.
  5. Click Add.

Service Accounts

A service account is a required field when creating a VDI profile — it must exist beforehand, and its attached role must already have access to the target cloudspace (see above). The service account then provisions and manages the VDI VMs in that cloudspace on the user's behalf; it has no built-in VDI-specific permissions of its own — whatever its attached role(s) permit is what it can do.

Creating a Service Account

  1. Open Service Accounts in the Admin group of the sidebar.
  2. Click ADD SERVICE ACCOUNT.
  3. Enter a Name.
  4. Under Roles, select the service account role you created above (with cloudspace access already granted).
  5. Click ADD SERVICE ACCOUNT.

Authorization Required

If your account does not yet have the IAM owner scope, the portal first shows an Authorization Required dialog ("The user:ownerof:organization scope for organization ... is needed to continue the operation!") with AUTHORIZE and CLOSE buttons. Click AUTHORIZE to continue; clicking CLOSE cancels the action.

VDI Sessions

A VDI Session represents an active connection between a user and a VM.

As the administrator, get the shareable link for your users:

  1. Navigate to the VDI Profile's details page.
  2. Click Agent Landing Page (top of the page).
  3. Share the resulting URL with your users.

This landing page is where users request sessions and, for Agent mode, download the VDI Agent installer for their operating system — see Install the VDI Agent.

Connecting to a Session

Agent Mode: on the landing page, install the VDI Agent if you haven't already (see Install the VDI Agent), click Start Session, and follow the on-screen connection progress. Once ready, log in on the remote desktop with your domain credentials.

RD Gateway Mode: on the landing page, click Start RDP Session. The .rdp file (or, on Linux, optionally a .remmina file) downloads automatically once the session is ready — open it and log in with your domain credentials.

Viewing Sessions

The profile's Sessions tab lists every session with its Session ID, User, Status, Created At, and Actions. Click a session to open its details page.

Session Details

A session's details page shows:

  • Session info: the VM ID (linked to the VM's own details page — see below), username, status, RDP target IP and port, created/updated timestamps.
  • Connected Agent VPN details (Agent mode only): the WireGuard public key, endpoint, and allowed IPs for this specific session's tunnel — distinct from the profile's own WireGuard interface on the WireGuard tab.
  • A Logs tab: a searchable log of events for this session, each with a source, level, message, and timestamp. Related consecutive log lines from the same source are grouped, with a button to expand the full grouped message.
  • A Status history tab: every state transition the session has gone through, with a reason and timestamp for each — useful for seeing exactly when and why a session moved between states (for example, why it failed).

Debugging via the VM Console

If a session's VM is misbehaving and the logs and status history don't explain why, click the session's VM ID to go straight to that VM's own details page, then use its Console button to get a direct console session on the VM itself — the same console access available for any VM on the platform. This is often the fastest way to check what's actually happening inside a stuck or failed VDI session's VM.

Ending a Session

Sessions normally end on their own: for single-use profiles the VM is recycled, and for dedicated profiles the VM shuts down once idle past the recycle time (if availability is set to shutdown).

To end one manually, select it from the sessions list and use the delete action. If the session still has an active VM, check Force delete to remove it anyway.

Session States

Sessions progress through these states:

  • initialized: Session created, VM not yet provisioned
  • reconnecting: Re-establishing the connection to an already-provisioned session
  • provisioning: VM being created, installing VDI agent
  • standby: VM ready, no user assigned
  • reserved: VM assigned to user, waiting for connection
  • connected: User connected via RDP
  • recycling: Single-use VM being reset
  • shutdown: Dedicated VM powered off after being idle past the recycle time (only for dedicated profiles with availability set to shutdown)
  • failed: Session encountered an error

Changing the Service Account

After a VDI profile is created, the service account can be changed via the pencil icon next to the service account field on the profile details page.

Direct Console Button on Sessions

On the VDI profile's Sessions tab, each session row with a VM has a dedicated Console button (monitor icon) that opens the VM console directly in a new window.

Session Count Tooltip

The VDI profiles list shows a total session count per profile. Hovering reveals a per-state breakdown (active, idle, etc.).

Copy-to-Clipboard for RD Gateway

On the VDI profile details page (RD Gateway mode), the public key and binary download URL have copy-to-clipboard buttons.

Rotating and Removing RD Gateway Keys

On the VDI profile details page (RD Gateway mode), you can rotate or remove the RD Gateway public key via the key management dialog.

Setting Up a Golden-Image Environment

Two guides cover preparing a Windows-based VDI environment, split out from this page since they're pure Windows/PowerShell walkthroughs rather than portal-UI reference:

  • Setting Up a Domain Controller — creating the Domain Controller VM that serves as the identity provider for your VDI environment.
  • Creating a Golden Image — preparing a Windows VM template with Sysprep, then validating and publishing it through the portal's test-and-publish workflow.